0
# Duration and Intervals
1

2
Time span calculations with support for years and months. The Duration class extends Python's timedelta with year and month support, while Interval represents the time span between two specific DateTime objects.
3

4
## Capabilities
5

6
### Duration Creation
7

8
Functions for creating Duration instances with comprehensive time unit support.
9

10
```python { .api }
11
def duration(
12
    days: float = 0,
13
    seconds: float = 0,
14
    microseconds: float = 0,
15
    milliseconds: float = 0,
16
    minutes: float = 0,
17
    hours: float = 0,
18
    weeks: float = 0,
19
    years: float = 0,
20
    months: float = 0
21
) -> Duration:
22
    """
23
    Create Duration instance.
24
    
25
    Parameters:
26
    - days: Number of days
27
    - seconds: Number of seconds
28
    - microseconds: Number of microseconds
29
    - milliseconds: Number of milliseconds
30
    - minutes: Number of minutes
31
    - hours: Number of hours
32
    - weeks: Number of weeks
33
    - years: Number of years (unique to Pendulum)
34
    - months: Number of months (unique to Pendulum)
35
    
36
    Returns:
37
    Duration: New Duration instance
38
    """
39
```
40

41
### Duration Class
42

43
The Duration class with its constructor and methods.
44

45
```python { .api }
46
class Duration:
47
    def __init__(
48
        self,
49
        days: float = 0,
50
        seconds: float = 0,
51
        microseconds: float = 0,
52
        milliseconds: float = 0,
53
        minutes: float = 0,
54
        hours: float = 0,
55
        weeks: float = 0,
56
        years: float = 0,
57
        months: float = 0
58
    ):
59
        """Create Duration with specified time components"""
60
    
61
    def total_seconds(self) -> float:
62
        """
63
        Total duration in seconds.
64
        
65
        Returns:
66
        float: Total seconds (excluding years/months)
67
        """
68
    
69
    def total_minutes(self) -> float:
70
        """
71
        Total duration in minutes.
72
        
73
        Returns:
74
        float: Total minutes
75
        """
76
    
77
    def total_hours(self) -> float:
78
        """
79
        Total duration in hours.
80
        
81
        Returns:
82
        float: Total hours
83
        """
84
    
85
    def total_days(self) -> float:
86
        """
87
        Total duration in days.
88
        
89
        Returns:
90
        float: Total days
91
        """
92
    
93
    def total_weeks(self) -> float:
94
        """
95
        Total duration in weeks.
96
        
97
        Returns:
98
        float: Total weeks
99
        """
100
    
101
    def in_weeks(self) -> int:
102
        """
103
        Duration as integer weeks.
104
        
105
        Returns:
106
        int: Number of complete weeks
107
        """
108
    
109
    def in_days(self) -> int:
110
        """
111
        Duration as integer days.
112
        
113
        Returns:
114
        int: Number of complete days
115
        """
116
    
117
    def in_hours(self) -> int:
118
        """
119
        Duration as integer hours.
120
        
121
        Returns:
122
        int: Number of complete hours
123
        """
124
    
125
    def in_minutes(self) -> int:
126
        """
127
        Duration as integer minutes.
128
        
129
        Returns:
130
        int: Number of complete minutes
131
        """
132
    
133
    def in_seconds(self) -> int:
134
        """
135
        Duration as integer seconds.
136
        
137
        Returns:
138
        int: Number of complete seconds
139
        """
140
    
141
    def in_words(self, locale: str | None = None, separator: str = " ") -> str:
142
        """
143
        Human-readable duration description.
144
        
145
        Parameters:
146
        - locale: Locale for formatting
147
        - separator: Separator between components
148
        
149
        Returns:
150
        str: Human-readable duration (e.g., "1 year 2 months 3 days")
151
        """
152
    
153
    def as_timedelta(self):
154
        """
155
        Convert to standard timedelta.
156
        
157
        Note: Years and months are converted to approximate days.
158
        
159
        Returns:
160
        timedelta: Standard timedelta object
161
        """
162
```
163

164
### Duration Properties
165

166
Properties available on Duration instances.
167

168
```python { .api }
169
class Duration:
170
    @property
171
    def years(self) -> int:
172
        """Number of years in duration"""
173
    
174
    @property
175
    def months(self) -> int:
176
        """Number of months in duration"""
177
    
178
    @property
179
    def weeks(self) -> int:
180
        """Number of weeks in duration"""
181
    
182
    @property
183
    def days(self) -> int:
184
        """Total days (including converted years/months)"""
185
    
186
    @property
187
    def remaining_days(self) -> int:
188
        """Days not included in weeks calculation"""
189
    
190
    @property
191
    def hours(self) -> int:
192
        """Hours component (0-23)"""
193
    
194
    @property
195
    def minutes(self) -> int:
196
        """Minutes component (0-59)"""
197
    
198
    @property
199
    def seconds(self) -> int:
200
        """Total seconds in duration"""
201
    
202
    @property
203
    def remaining_seconds(self) -> int:
204
        """Seconds component not included in larger units (0-59)"""
205
    
206
    @property
207
    def microseconds(self) -> int:
208
        """Microseconds component"""
209
    
210
    @property
211
    def invert(self) -> bool:
212
        """Whether duration is negative"""
213
```
214

215
### Interval Creation
216

217
Functions for creating Interval instances between DateTime objects.
218

219
```python { .api }
220
def interval(start: DateTime, end: DateTime, absolute: bool = False) -> Interval:
221
    """
222
    Create Interval between two DateTime objects.
223
    
224
    Parameters:
225
    - start: Start DateTime
226
    - end: End DateTime
227
    - absolute: Whether to make interval absolute (always positive)
228
    
229
    Returns:
230
    Interval: Time interval between the DateTimes
231
    """
232
```
233

234
### Interval Class
235

236
The Interval class representing time spans between specific points.
237

238
```python { .api }
239
class Interval(Duration):
240
    """
241
    Interval inherits all Duration methods and properties.
242
    Represents the time span between two DateTime objects.
243
    """
244
    
245
    def __init__(self, start: DateTime, end: DateTime, absolute: bool = False):
246
        """Create Interval between DateTimes"""
247
    
248
    @property
249
    def start(self) -> DateTime:
250
        """Start DateTime of interval"""
251
    
252
    @property
253
    def end(self) -> DateTime:
254
        """End DateTime of interval"""
255
    
256
    @property
257
    def years(self) -> int:
258
        """Years in interval"""
259
    
260
    @property
261
    def months(self) -> int:
262
        """Months in interval"""
263
    
264
    @property
265
    def weeks(self) -> int:
266
        """Weeks in interval"""
267
    
268
    @property
269
    def days(self) -> int:
270
        """Days in interval"""
271
```
272

273
## Usage Examples
274

275
### Creating and Using Durations
276

277
```python
278
import pendulum
279

280
# Create durations
281
dur1 = pendulum.duration(hours=2, minutes=30)
282
dur2 = pendulum.duration(years=1, months=6, days=15)
283
dur3 = pendulum.duration(weeks=2, days=3, hours=4)
284

285
# Access components
286
print(f"Years: {dur2.years}")        # 1
287
print(f"Months: {dur2.months}")      # 6  
288
print(f"Days: {dur2.days}")          # 15 + ~365 + ~182 = ~562
289
print(f"Hours: {dur1.hours}")        # 2
290
print(f"Minutes: {dur1.minutes}")    # 30
291

292
# Total calculations
293
print(f"Total hours: {dur1.total_hours()}")      # 2.5
294
print(f"Total seconds: {dur1.total_seconds()}")  # 9000.0
295

296
# Integer conversions
297
print(f"In hours: {dur1.in_hours()}")      # 2
298
print(f"In minutes: {dur1.in_minutes()}")  # 150
299

300
# Human-readable format
301
print(dur2.in_words())  # "1 year 6 months 15 days"
302
print(dur1.in_words())  # "2 hours 30 minutes"
303

304
# Convert to standard timedelta
305
td = dur1.as_timedelta()
306
print(type(td))  # <class 'datetime.timedelta'>
307
```
308

309
### Using Durations with DateTimes
310

311
```python
312
import pendulum
313

314
dt = pendulum.now()
315

316
# Add/subtract durations
317
future = dt + pendulum.duration(years=1, months=2)
318
past = dt - pendulum.duration(weeks=3, days=2)
319

320
# Duration arithmetic with DateTime methods
321
future2 = dt.add(years=1, months=2, days=5)
322
past2 = dt.subtract(hours=6, minutes=30)
323

324
# Complex duration
325
complex_dur = pendulum.duration(
326
    years=2,
327
    months=3, 
328
    weeks=1,
329
    days=4,
330
    hours=5,
331
    minutes=30,
332
    seconds=45
333
)
334

335
result = dt + complex_dur
336
print(f"Added duration: {result}")
337
print(f"Duration in words: {complex_dur.in_words()}")
338
```
339

340
### Working with Intervals
341

342
```python
343
import pendulum
344

345
# Create interval between two dates
346
start = pendulum.datetime(2024, 1, 1)
347
end = pendulum.datetime(2025, 6, 15)
348
interval = pendulum.interval(start, end)
349

350
# Access interval properties
351
print(f"Years: {interval.years}")
352
print(f"Months: {interval.months}")
353
print(f"Days: {interval.days}")
354

355
# Interval inherits Duration methods
356
print(f"Total days: {interval.total_days()}")
357
print(f"In words: {interval.in_words()}")
358

359
# Create interval from DateTime.diff()
360
dt1 = pendulum.now()
361
dt2 = dt1.add(months=3, days=10)
362
diff_interval = dt1.diff(dt2)  # Returns Interval
363

364
print(f"Difference: {diff_interval.in_words()}")
365

366
# Absolute intervals
367
past_dt = pendulum.now().subtract(days=30)
368
future_dt = pendulum.now().add(days=30)
369

370
# Normal interval (negative)
371
normal = pendulum.interval(future_dt, past_dt)
372
print(f"Normal: {normal.total_days()}")  # -60
373

374
# Absolute interval (positive)
375
absolute = pendulum.interval(future_dt, past_dt, absolute=True)
376
print(f"Absolute: {absolute.total_days()}")  # 60
377
```
378

379
### Duration Comparisons and Operations
380

381
```python
382
import pendulum
383

384
dur1 = pendulum.duration(hours=2)
385
dur2 = pendulum.duration(minutes=120)
386
dur3 = pendulum.duration(hours=3)
387

388
# Duration comparison
389
print(dur1 == dur2)  # True (both are 2 hours)
390
print(dur1 < dur3)   # True
391
print(dur1 > dur3)   # False
392

393
# Duration arithmetic
394
combined = dur1 + dur3  # 5 hours
395
difference = dur3 - dur1  # 1 hour
396

397
# Multiplication and division
398
doubled = dur1 * 2      # 4 hours
399
half = dur1 / 2         # 1 hour
400

401
print(f"Combined: {combined.in_words()}")
402
print(f"Difference: {difference.in_words()}")
403
print(f"Doubled: {doubled.in_words()}")
404
print(f"Half: {half.in_words()}")
405
```
406

407
### Negative Durations
408

409
```python
410
import pendulum
411

412
# Create negative duration
413
neg_dur = pendulum.duration(hours=-2, minutes=-30)
414
print(f"Negative duration: {neg_dur.invert}")  # True
415
print(f"In words: {neg_dur.in_words()}")
416

417
# Use with DateTime
418
dt = pendulum.now()
419
past_time = dt + neg_dur  # Same as dt.subtract(hours=2, minutes=30)
420

421
# Interval creating negative duration
422
start = pendulum.now()
423
end = start.subtract(hours=5)
424
negative_interval = pendulum.interval(start, end)
425
print(f"Negative interval: {negative_interval.invert}")
426
```
427

428
### Converting Between Duration Types
429

430
```python
431
import pendulum
432
import datetime
433

434
# Pendulum Duration to standard timedelta
435
pd_dur = pendulum.duration(days=5, hours=3, minutes=30)
436
std_td = pd_dur.as_timedelta()
437

438
# Use standard timedelta with Pendulum DateTimes
439
dt = pendulum.now()
440
future = dt + std_td
441

442
# Note: Years and months are converted to approximate days
443
complex_dur = pendulum.duration(years=1, months=2, days=5)
444
# This conversion is approximate since months/years vary in length
445
approx_td = complex_dur.as_timedelta()
446

447
print(f"Original: {complex_dur.in_words()}")
448
print(f"As timedelta days: {approx_td.days}")
449
```