Date

class whenever.Date(iso_string: str, /)

class whenever.Date(py_date: date, /)

class whenever.Date(year: int, month: int, day: int)

A date without a time component.

>>> d = Date(2021, 1, 2)
Date("2021-01-02")

Can also be constructed from an ISO 8601 string or a standard library date:

>>> Date("2021-01-02")
Date("2021-01-02")
>>> Date(date(2021, 1, 2))
Date("2021-01-02")

Dates support arithmetic with ItemizedDateDelta:

>>> delta = Date("2021-02-28").since(Date("1994-05-15"), in_units=["years", "days"])
ItemizedDateDelta("P26y289d")
>>> Date("1994-05-15").add(delta)
Date("2021-02-28")

Dates can be compared and sorted:

>>> Date(2021, 1, 2) > Date(2021, 1, 1)
True

classmethod from_py_date(d: date, /) → Date

Create from a date

>>> Date.from_py_date(date(2021, 1, 2))
Date("2021-01-02")

Deprecated since version 0.10.0: Use the constructor Date(d) instead.

classmethod parse(s: str, /, *, format: str) → Date

Parse a date from a custom pattern string.

See Pattern format for details.

>>> Date.parse("2024/03/15", format="YYYY/MM/DD")
Date("2024-03-15")
>>> Date.parse("15 Mar 2024", format="DD MMM YYYY")
Date("2024-03-15")

classmethod parse_iso(s: str, /) → Date

Parse a date from an ISO8601 string

The following formats are accepted: - YYYY-MM-DD (“extended” format) - YYYYMMDD (“basic” format)

Inverse of format_iso()

>>> Date.parse_iso("2021-01-02")
Date("2021-01-02")

classmethod today_in_system_tz() → Date

Get the current date in the system’s local timezone.

Alias for Instant.now().to_system_tz().date().

>>> Date.today_in_system_tz()
Date("2021-01-02")

__add__(p: DateDelta) → Date

Add a delta to a date. Behaves the same as add()

Deprecated since version 0.10.0: Using the + operator on Date is deprecated; use the add() method instead.

__eq__(other: object) → bool

Compare for equality

>>> d = Date(2021, 1, 2)
>>> d == Date(2021, 1, 2)
True
>>> d == Date(2021, 1, 3)
False

__format__(spec: str, /) → str

Default object formatter.

Return str(self) if format_spec is empty. Raise TypeError otherwise.

__ge__(other: Date) → bool

Return self>=value.

__gt__(other: Date) → bool

Return self>value.

__le__(other: Date) → bool

Return self<=value.

__lt__(other: Date) → bool

Return self<value.

__str__(*, basic: bool = False) → str

Format as the ISO 8601 date format.

Inverse of parse_iso().

>>> Date(2021, 1, 2).format_iso()
'2021-01-02'
>>> Date(1992, 9, 4).format_iso(basic=True)
'19920904'

__sub__(d: DateDelta) → Date

__sub__(d: Date) → DateDelta

Subtract a delta from a date, or subtract two dates

Subtracting a delta works the same as subtract().

>>> Date(2021, 1, 2) - DateDelta(weeks=1, days=3)
Date("2020-12-26")

The difference between two dates is calculated in months and days, such that:

>>> delta = d1 - d2
>>> d2 + delta == d1  # always

The following is not always true:

>>> d1 - (d1 - d2) == d2  # not always true!
>>> -(d2 - d1) == d1 - d2  # not always true!

>>> Date(2023, 4, 15) - Date(2011, 6, 24)
DateDelta("P12Y9M22D")
>>> # Truncation
>>> Date(2024, 4, 30) - Date(2023, 5, 31)
DateDelta("P11M")
>>> Date(2024, 3, 31) - Date(2023, 6, 30)
DateDelta("P9M1D")
>>> # the other way around, the result is different
>>> Date(2023, 6, 30) - Date(2024, 3, 31)
DateDelta(-P9M)

Deprecated since version 0.10.0: Using the - operator on Date is deprecated; use the subtract() method or the since() method instead.

add(delta: ItemizedDateDelta | DateDelta, /) → Date

add(*, years: int = ..., months: int = ..., weeks: int = ..., days: int = ...) → Date

Add a components to a date.

See the docs on arithmetic for more information.

>>> d = Date(2021, 1, 2)
>>> d.add(years=1, months=2, days=3)
Date("2022-03-05")
>>> Date(2020, 2, 29).add(years=1)
Date("2021-02-28")

at(t: Time, /) → PlainDateTime

Combine a date with a time to create a datetime

>>> d = Date(2021, 1, 2)
>>> d.at(Time(12, 30))
PlainDateTime("2021-01-02 12:30:00")

You can use methods like assume_utc() or assume_tz() to find the corresponding exact time.

day_of_week() → Weekday

The day of the week

>>> Date(2021, 1, 2).day_of_week()
Weekday.SATURDAY
>>> Weekday.SATURDAY.value
6  # the ISO value

day_of_year() → int

Ordinal day in the year (1–366)

>>> Date(2021, 1, 2).day_of_year()
2
>>> Date(2021, 12, 31).day_of_year()
365

days_in_month() → int

Number of days in the current month (28–31)

>>> Date(2024, 2, 1).days_in_month()
29
>>> Date(2023, 2, 1).days_in_month()
28

days_in_year() → int

Number of days in the current year (365 or 366)

>>> Date(2024, 1, 1).days_in_year()
366
>>> Date(2023, 1, 1).days_in_year()
365

days_since(other: Date, /) → int

Calculate the number of days this day is after another date.

Deprecated since version 0.10.0: Use since() with unit=”days” instead.

days_until(other: Date, /) → int

Calculate the number of days from this date to another date.

Deprecated since version 0.10.0: Use until() with unit=”days” instead.

end_of(unit: Literal['year', 'month'], /) → Date

The end of the given calendar unit

>>> Date(2024, 8, 15).end_of("year")
Date("2024-12-31")
>>> Date(2024, 8, 15).end_of("month")
Date("2024-08-31")

See also start_of()

format(pattern: str, /) → str

Format as a custom pattern string.

See Pattern format for details.

>>> Date(2024, 3, 15).format("YYYY/MM/DD")
'2024/03/15'
>>> Date(2024, 3, 15).format("DD MMM YYYY")
'15 Mar 2024'

format_iso(*, basic: bool = False) → str

Format as the ISO 8601 date format.

Inverse of parse_iso().

>>> Date(2021, 1, 2).format_iso()
'2021-01-02'
>>> Date(1992, 9, 4).format_iso(basic=True)
'19920904'

in_leap_year() → bool

Whether this date’s year is a leap year

>>> Date(2024, 1, 1).in_leap_year()
True
>>> Date(2023, 1, 1).in_leap_year()
False

iso_week_date() → IsoWeekDate

The ISO week date for this date

>>> Date(2024, 12, 30).iso_week_date()
IsoWeekDate("2025-W01-1")

month_day() → MonthDay

The month and day (without a year component)

>>> Date(2021, 1, 2).month_day()
MonthDay("--01-02")

next_day() → Date

The date immediately following

>>> Date(2021, 1, 2).next_day()
Date("2021-01-03")

nth_weekday(n: int, weekday: Weekday, /) → Date

The n-th occurrence of a weekday from this date (exclusive).

Negative n searches backward. n=0 raises ValueError.

>>> Date(2024, 8, 1).nth_weekday(1, Weekday.FRIDAY)
Date("2024-08-02")
>>> Date(2024, 8, 1).nth_weekday(-1, Weekday.WEDNESDAY)
Date("2024-07-31")

nth_weekday_of_month(n: int, weekday: Weekday, /) → Date

The n-th occurrence of a weekday in this date’s month.

Negative n counts from the end. n=0 raises ValueError.

>>> Date(2024, 8, 1).nth_weekday_of_month(2, Weekday.FRIDAY)
Date("2024-08-09")
>>> Date(2024, 8, 1).nth_weekday_of_month(-1, Weekday.FRIDAY)
Date("2024-08-30")

prev_day() → Date

The date immediately preceding

>>> Date(2021, 1, 2).prev_day()
Date("2021-01-01")

py_date() → date

Convert to a standard library date

Deprecated since version 0.10.0: Use to_stdlib() instead.

replace(year: int = ..., month: int = ..., day: int = ...) → Date

Create a new instance with the given fields replaced

>>> d = Date(2021, 1, 2)
>>> d.replace(day=4)
Date("2021-01-04")

since(b: Date, /, *, total: DateDeltaUnitStr) → float

since(

b: Date,

/,

*,

in_units: Sequence[TypeAliasForwardRef('DateDeltaUnitStr')],

round_mode: RoundModeStr = 'trunc',

round_increment: int = ...,

) → ItemizedDateDelta

Calculate the difference between this date and another date. The difference is calculated in terms of the chosen calendar unit or units.

>>> d = Date(2023, 4, 15)
>>> d.since(Date("2020-01-01"), in_units=["years", "months"])
ItemizedDateDelta("P3y3m")

>>> d.since(Date("2020-01-01"), total="weeks")
170.0

Parameters:

• other – The date to calculate the difference since.

• total –

  If specified, the difference is returned as a float in terms of this single unit. Cannot be combined with in_units.

  The fractional part is based on the number of days in the surrounding calendar period — not a fixed conversion factor. For example, 6 months from January 1 spans 181 days of a 365-day year, giving approximately 0.496 years, not 0.5.

• in_units – If specified, the difference is calculated in terms of these units, in decreasing order of size. Cannot be combined with total.

• round_mode – The rounding mode to apply to the smallest specified unit. Only valid with in_units.

• round_increment – The increment to round to for the smallest specified unit. Only valid with in_units.

Returns:

If in_units is specified, the difference is returned as an ItemizedDateDelta, If total is specified, as a float number of the specified unit.

Return type:

ItemizedDateDelta | float

start_of(unit: Literal['year', 'month'], /) → Date

The start of the given calendar unit

>>> Date(2024, 8, 15).start_of("year")
Date("2024-01-01")
>>> Date(2024, 8, 15).start_of("month")
Date("2024-08-01")

Note

"week" is not a valid unit because weeks do not have a universal start day. Use nth_weekday() instead.

subtract(delta: ItemizedDateDelta | DateDelta, /) → Date

subtract(*, years: int = ..., months: int = ..., weeks: int = ..., days: int = ...) → Date

Subtract components from a date.

See the docs on arithmetic for more information.

>>> d = Date(2021, 1, 2)
>>> d.subtract(years=1, months=2, days=3)
Date("2019-10-30")
>>> Date(2021, 3, 1).subtract(years=1)
Date("2020-03-01")

to_stdlib() → date

Convert to a standard library date

until(b: Date, /, *, total: DateDeltaUnitStr) → float

until(

b: Date,

/,

*,

in_units: Sequence[TypeAliasForwardRef('DateDeltaUnitStr')],

round_mode: RoundModeStr = 'trunc',

round_increment: int = ...,

) → ItemizedDateDelta

Companion to since() that calculates the difference until another date. See since() for more information.

year_month() → YearMonth

The year and month (without a day component)

>>> Date(2021, 1, 2).year_month()
YearMonth("2021-01")

MAX: ClassVar[Date] = Date("9999-12-31")

The maximum possible date

MIN: ClassVar[Date] = Date("0001-01-01")

The minimum possible date

property day: int

The day component of the date

>>> Date(2021, 1, 2).day
2

property month: int

The month component of the date

>>> Date(2021, 1, 2).month
1

property year: int

The year component of the date

>>> Date(2021, 1, 2).year
2021