0
# Date and Time Components
1
2
Specialized classes for working with date-only and time-only values. The Date class provides date functionality without time components, while the Time class handles time values without date information.
3
4
## Capabilities
5
6
### Date Creation
7
8
Functions and methods for creating Date instances.
9
10
```python { .api }
11
def date(year: int, month: int, day: int) -> Date:
12
"""
13
Create Date instance.
14
15
Parameters:
16
- year: Year (1-9999)
17
- month: Month (1-12)
18
- day: Day (1-31)
19
20
Returns:
21
Date: New Date instance
22
"""
23
```
24
25
### Date Class Methods
26
27
Class methods available on the Date class.
28
29
```python { .api }
30
class Date:
31
@classmethod
32
def today(cls) -> Date:
33
"""Get current date"""
34
35
@classmethod
36
def fromtimestamp(cls, timestamp: float) -> Date:
37
"""Create Date from timestamp"""
38
39
@classmethod
40
def fromordinal(cls, ordinal: int) -> Date:
41
"""Create Date from ordinal day number"""
42
```
43
44
### Date Instance Methods
45
46
Methods for manipulating and working with Date instances.
47
48
```python { .api }
49
class Date:
50
def set(
51
self,
52
year: int | None = None,
53
month: int | None = None,
54
day: int | None = None
55
) -> Date:
56
"""
57
Set date components.
58
59
Returns:
60
Date: New Date with specified components
61
"""
62
63
def replace(
64
self,
65
year: int | None = None,
66
month: int | None = None,
67
day: int | None = None
68
) -> Date:
69
"""
70
Replace date components.
71
72
Returns:
73
Date: New Date with replaced components
74
"""
75
76
def add(
77
self,
78
years: int = 0,
79
months: int = 0,
80
weeks: int = 0,
81
days: int = 0
82
) -> Date:
83
"""
84
Add time period to Date.
85
86
Returns:
87
Date: New Date with added period
88
"""
89
90
def subtract(
91
self,
92
years: int = 0,
93
months: int = 0,
94
weeks: int = 0,
95
days: int = 0
96
) -> Date:
97
"""
98
Subtract time period from Date.
99
100
Returns:
101
Date: New Date with subtracted period
102
"""
103
104
def start_of(self, unit: str) -> Date:
105
"""
106
Move to start of time unit.
107
108
Parameters:
109
- unit: 'week', 'month', 'year', 'decade', 'century'
110
111
Returns:
112
Date: Date at start of specified unit
113
"""
114
115
def end_of(self, unit: str) -> Date:
116
"""
117
Move to end of time unit.
118
119
Parameters:
120
- unit: 'week', 'month', 'year', 'decade', 'century'
121
122
Returns:
123
Date: Date at end of specified unit
124
"""
125
126
def next(self, day_of_week: WeekDay | None = None) -> Date:
127
"""
128
Get next occurrence of weekday.
129
130
Parameters:
131
- day_of_week: Target weekday (None for next day)
132
133
Returns:
134
Date: Next occurrence
135
"""
136
137
def previous(self, day_of_week: WeekDay | None = None) -> Date:
138
"""
139
Get previous occurrence of weekday.
140
141
Parameters:
142
- day_of_week: Target weekday (None for previous day)
143
144
Returns:
145
Date: Previous occurrence
146
"""
147
148
def first_of(self, unit: str, day_of_week: WeekDay | None = None) -> Date:
149
"""
150
Get first occurrence in time unit.
151
152
Parameters:
153
- unit: 'month', 'quarter', 'year'
154
- day_of_week: Specific weekday (None for first day)
155
156
Returns:
157
Date: First occurrence in unit
158
"""
159
160
def last_of(self, unit: str, day_of_week: WeekDay | None = None) -> Date:
161
"""
162
Get last occurrence in time unit.
163
164
Parameters:
165
- unit: 'month', 'quarter', 'year'
166
- day_of_week: Specific weekday (None for last day)
167
168
Returns:
169
Date: Last occurrence in unit
170
"""
171
172
def nth_of(self, unit: str, nth: int, day_of_week: WeekDay) -> Date:
173
"""
174
Get nth occurrence of weekday in time unit.
175
176
Parameters:
177
- unit: 'month', 'quarter', 'year'
178
- nth: Occurrence number (1-5, -1 for last)
179
- day_of_week: Target weekday
180
181
Returns:
182
Date: Nth occurrence
183
"""
184
185
def average(self, dt: Date | None = None) -> Date:
186
"""
187
Get average Date between this and another.
188
189
Parameters:
190
- dt: Other Date (defaults to today)
191
192
Returns:
193
Date: Average Date
194
"""
195
196
def closest(self, *dates: Date) -> Date:
197
"""
198
Get closest Date from list.
199
200
Parameters:
201
- *dates: Date objects to compare
202
203
Returns:
204
Date: Closest Date
205
"""
206
207
def farthest(self, *dates: Date) -> Date:
208
"""
209
Get farthest Date from list.
210
211
Parameters:
212
- *dates: Date objects to compare
213
214
Returns:
215
Date: Farthest Date
216
"""
217
218
def is_future(self) -> bool:
219
"""Check if Date is in the future"""
220
221
def is_past(self) -> bool:
222
"""Check if Date is in the past"""
223
224
def is_leap_year(self) -> bool:
225
"""Check if year is a leap year"""
226
227
def is_long_year(self) -> bool:
228
"""Check if ISO year has 53 weeks"""
229
230
def is_same_day(self, dt: Date) -> bool:
231
"""Check if same day as another Date"""
232
233
def is_anniversary(self, dt: Date | None = None) -> bool:
234
"""Check if anniversary date (same month/day)"""
235
236
def is_birthday(self, dt: Date | None = None) -> bool:
237
"""Alias for is_anniversary()"""
238
239
def diff(self, dt: Date | None = None, abs: bool = True) -> Interval:
240
"""
241
Calculate difference as Interval.
242
243
Parameters:
244
- dt: Other Date (defaults to today)
245
- abs: Whether to return absolute difference
246
247
Returns:
248
Interval: Time difference
249
"""
250
251
def diff_for_humans(
252
self,
253
other: Date | None = None,
254
absolute: bool = False,
255
locale: str | None = None
256
) -> str:
257
"""
258
Get human-readable difference description.
259
260
Parameters:
261
- other: Other Date (defaults to today)
262
- absolute: Whether to omit ago/from now
263
- locale: Locale for formatting
264
265
Returns:
266
str: Human-readable difference
267
"""
268
269
def to_date_string(self) -> str:
270
"""Format as YYYY-MM-DD"""
271
272
def to_formatted_date_string(self) -> str:
273
"""Format as "Dec 25, 2013" """
274
275
def format(self, fmt: str, locale: str | None = None) -> str:
276
"""
277
Format using custom format string.
278
279
Parameters:
280
- fmt: Format pattern
281
- locale: Locale for formatting
282
283
Returns:
284
str: Formatted date string
285
"""
286
```
287
288
### Date Properties
289
290
Properties available on Date instances.
291
292
```python { .api }
293
class Date:
294
@property
295
def day_of_week(self) -> WeekDay:
296
"""Day of week as WeekDay enum (0-6)"""
297
298
@property
299
def day_of_year(self) -> int:
300
"""Day of year (1-366)"""
301
302
@property
303
def week_of_year(self) -> int:
304
"""ISO week number (1-53)"""
305
306
@property
307
def days_in_month(self) -> int:
308
"""Number of days in month"""
309
310
@property
311
def week_of_month(self) -> int:
312
"""Week of month (1-6)"""
313
314
@property
315
def age(self) -> int:
316
"""Age in years from today"""
317
318
@property
319
def quarter(self) -> int:
320
"""Quarter of year (1-4)"""
321
```
322
323
### Time Creation
324
325
Functions and methods for creating Time instances.
326
327
```python { .api }
328
def time(
329
hour: int,
330
minute: int = 0,
331
second: int = 0,
332
microsecond: int = 0
333
) -> Time:
334
"""
335
Create Time instance.
336
337
Parameters:
338
- hour: Hour (0-23)
339
- minute: Minute (0-59)
340
- second: Second (0-59)
341
- microsecond: Microsecond (0-999999)
342
343
Returns:
344
Time: New Time instance
345
"""
346
```
347
348
### Time Class Methods
349
350
Class methods available on the Time class.
351
352
```python { .api }
353
class Time:
354
@classmethod
355
def instance(cls, t, tz=None) -> Time:
356
"""
357
Create Time from standard time object.
358
359
Parameters:
360
- t: Standard time object
361
- tz: Timezone (ignored for Time objects)
362
363
Returns:
364
Time: New Time instance
365
"""
366
```
367
368
### Time Instance Methods
369
370
Methods for manipulating and working with Time instances.
371
372
```python { .api }
373
class Time:
374
def add(
375
self,
376
hours: int = 0,
377
minutes: int = 0,
378
seconds: int = 0,
379
microseconds: int = 0
380
) -> Time:
381
"""
382
Add time duration to Time.
383
384
Returns:
385
Time: New Time with added duration
386
"""
387
388
def subtract(
389
self,
390
hours: int = 0,
391
minutes: int = 0,
392
seconds: int = 0,
393
microseconds: int = 0
394
) -> Time:
395
"""
396
Subtract time duration from Time.
397
398
Returns:
399
Time: New Time with subtracted duration
400
"""
401
402
def add_timedelta(self, delta) -> Time:
403
"""
404
Add timedelta to Time.
405
406
Parameters:
407
- delta: timedelta object
408
409
Returns:
410
Time: New Time with added delta
411
"""
412
413
def subtract_timedelta(self, delta) -> Time:
414
"""
415
Subtract timedelta from Time.
416
417
Parameters:
418
- delta: timedelta object
419
420
Returns:
421
Time: New Time with subtracted delta
422
"""
423
424
def replace(
425
self,
426
hour: int | None = None,
427
minute: int | None = None,
428
second: int | None = None,
429
microsecond: int | None = None,
430
tzinfo: bool = True,
431
fold: int = 0
432
) -> Time:
433
"""
434
Replace time components.
435
436
Returns:
437
Time: New Time with replaced components
438
"""
439
440
def closest(self, *times: Time) -> Time:
441
"""
442
Get closest Time from list.
443
444
Parameters:
445
- *times: Time objects to compare
446
447
Returns:
448
Time: Closest Time
449
"""
450
451
def farthest(self, *times: Time) -> Time:
452
"""
453
Get farthest Time from list.
454
455
Parameters:
456
- *times: Time objects to compare
457
458
Returns:
459
Time: Farthest Time
460
"""
461
462
def diff(self, t: Time | None = None, abs: bool = True) -> Duration:
463
"""
464
Calculate difference as Duration.
465
466
Parameters:
467
- t: Other Time (defaults to current time)
468
- abs: Whether to return absolute difference
469
470
Returns:
471
Duration: Time difference
472
"""
473
474
def diff_for_humans(
475
self,
476
other: Time | None = None,
477
absolute: bool = False,
478
locale: str | None = None
479
) -> str:
480
"""
481
Get human-readable difference description.
482
483
Parameters:
484
- other: Other Time (defaults to current time)
485
- absolute: Whether to omit ago/from now
486
- locale: Locale for formatting
487
488
Returns:
489
str: Human-readable difference
490
"""
491
492
def format(self, fmt: str, locale: str | None = None) -> str:
493
"""
494
Format using custom format string.
495
496
Parameters:
497
- fmt: Format pattern
498
- locale: Locale for formatting
499
500
Returns:
501
str: Formatted time string
502
"""
503
```
504
505
### Time Constants
506
507
Constants available on the Time class.
508
509
```python { .api }
510
class Time:
511
min: Time # 00:00:00
512
max: Time # 23:59:59.999999
513
resolution: timedelta # 1 microsecond
514
```
515
516
## Usage Examples
517
518
### Working with Dates
519
520
```python
521
import pendulum
522
523
# Create dates
524
today = pendulum.Date.today()
525
date = pendulum.date(2024, 3, 15)
526
527
# Date arithmetic
528
future_date = date.add(months=6, days=10)
529
past_date = date.subtract(years=1)
530
531
# Navigation
532
start_month = date.start_of('month')
533
end_year = date.end_of('year')
534
next_friday = date.next(pendulum.FRIDAY)
535
536
# Properties
537
print(f"Day of week: {date.day_of_week}")
538
print(f"Week of year: {date.week_of_year}")
539
print(f"Quarter: {date.quarter}")
540
541
# Comparisons
542
if date.is_future():
543
print("Future date")
544
545
# Formatting
546
print(date.to_date_string()) # 2024-03-15
547
print(date.to_formatted_date_string()) # Mar 15, 2024
548
print(date.format('MMMM Do, YYYY')) # March 15th, 2024
549
```
550
551
### Working with Times
552
553
```python
554
import pendulum
555
556
# Create times
557
time = pendulum.time(14, 30, 15)
558
current_time = pendulum.Time.instance(datetime.time(9, 0))
559
560
# Time arithmetic
561
later = time.add(hours=2, minutes=30)
562
earlier = time.subtract(minutes=45)
563
564
# Using timedelta
565
import datetime
566
delta = datetime.timedelta(hours=1)
567
adjusted = time.add_timedelta(delta)
568
569
# Comparisons
570
times = [
571
pendulum.time(9, 0),
572
pendulum.time(14, 30),
573
pendulum.time(18, 45)
574
]
575
closest = time.closest(*times)
576
577
# Formatting
578
print(time.format('HH:mm:ss')) # 14:30:15
579
print(time.format('h:mm A')) # 2:30 PM
580
```
581
582
### Converting Between Components
583
584
```python
585
import pendulum
586
587
# Get components from DateTime
588
dt = pendulum.now()
589
date_part = dt.date()
590
time_part = dt.time()
591
592
# Standard datetime compatibility
593
std_date = dt.date() # Returns pendulum.Date
594
std_time = dt.time() # Returns pendulum.Time
595
596
# Create DateTime from Date and Time using standard datetime
597
import datetime
598
combined = datetime.datetime.combine(date_part, time_part)
599
back_to_pendulum = pendulum.instance(combined)
600
```