Deprecated components

whenever.years(i: int, /) → DateDelta

Create a DateDelta with the given number of years. years(1) == DateDelta(years=1)

Deprecated since version 0.10.0: Use ItemizedDateDelta instead

whenever.months(i: int, /) → DateDelta

Create a DateDelta with the given number of months. months(1) == DateDelta(months=1)

Deprecated since version 0.10.0: Use ItemizedDateDelta instead

whenever.weeks(i: int, /) → DateDelta

Create a DateDelta with the given number of weeks. weeks(1) == DateDelta(weeks=1)

Deprecated since version 0.10.0: Use ItemizedDateDelta instead

whenever.days(i: int, /) → DateDelta

Create a DateDelta with the given number of days. days(1) == DateDelta(days=1)

Deprecated since version 0.10.0: Use ItemizedDateDelta instead

exception whenever.ImplicitlyIgnoringDST

Raised when an operation would silently ignore DST transitions.

Deprecated since version 0.10.0: This exception is deprecated and will be removed in a future version.

final class whenever.DateDelta(iso_string: str, /)

final class whenever.DateDelta(*, years: int = ..., months: int = ..., weeks: int = ..., days: int = ...)

A duration of time consisting of calendar units (years, months, weeks, and days).

Deprecated since version 0.10.0: Use ItemizedDateDelta instead. DateDelta normalizes its inputs (e.g. 14 months becomes 1 year and 2 months), losing the original fields. ItemizedDateDelta preserves the exact fields it was created with.

classmethod parse_iso(s: str, /) → DateDelta

Parse the popular interpretation of the ISO 8601 duration format. Does not parse all possible ISO 8601 durations. See here for more information.

Inverse of format_iso()

>>> DateDelta.parse_iso("P1W11D")
DateDelta("P1w11d")
>>> DateDelta.parse_iso("-P3m")
DateDelta(-P3m)

Note

Only durations without time component are accepted. P0D is valid, but PT0S is not.

Note

The number of digits in each component is limited to 8.

__abs__() → DateDelta

If the contents are negative, return the positive version

>>> p = DateDelta(months=-2, days=-3)
>>> abs(p)
DateDelta("P2m3d")

__add__(other: DateDelta) → DateDelta

__add__(other: TimeDelta) → DateTimeDelta

Add the fields of another delta to this one

>>> p = DateDelta(weeks=2, months=1)
>>> p + DateDelta(weeks=1, days=4)
DateDelta("P1m25d")

__bool__() → bool

True if any contains any non-zero data

>>> bool(DateDelta())
False
>>> bool(DateDelta(days=-1))
True

__eq__(other: object) → bool

Compare for equality, normalized to months and days.

a == b is equivalent to a.in_months_days() == b.in_months_days()

>>> p = DateDelta(weeks=4, days=2)
DateDelta("P30d")
>>> p == DateDelta(weeks=3, days=9)
True
>>> p == DateDelta(weeks=2, days=4)
True  # same number of days
>>> p == DateDelta(months=1)
False  # months and days cannot be compared directly

__mul__(other: int) → DateDelta

Multiply the contents by a round number

>>> p = DateDelta(years=1, weeks=2)
>>> p * 2
DateDelta("P2y28d")

__neg__() → DateDelta

Negate the contents

>>> p = DateDelta(weeks=2, days=3)
>>> -p
DateDelta(-P17d)

__sub__(other: DateDelta) → DateDelta

__sub__(other: TimeDelta) → DateTimeDelta

Subtract the fields of another delta from this one

>>> p = DateDelta(weeks=2, days=3)
>>> p - DateDelta(days=2)
DateDelta("P15d")

format_iso() → str

Format as the popular interpretation of the ISO 8601 duration format. May not strictly adhere to (all versions of) the standard. See here for more information.

Inverse of parse_iso().

>>> p = DateDelta(years=1, months=2, weeks=3, days=11)
>>> p.format_iso()
'P1Y2M3W11D'
>>> DateDelta().format_iso()
'P0D'

The format looks like this:

P(nY)(nM)(nD)

For example:

P1D
P2M
P1Y2M3W4D

in_months_days() → tuple[int, int]

Convert to a tuple of months and days.

>>> p = DateDelta(months=25, days=9)
>>> p.in_months_days()
(25, 9)
>>> DateDelta(months=-13, weeks=-5)
(-13, -35)

in_years_months_days() → tuple[int, int, int]

Convert to a tuple of years, months, and days.

>>> p = DateDelta(years=1, months=2, days=11)
>>> p.in_years_months_days()
(1, 2, 11)

ZERO: ClassVar[DateDelta] = DateDelta("P0d")

A delta of zero

final class whenever.DateTimeDelta(iso_string: str, /)

final class whenever.DateTimeDelta(

*,

years: int = ...,

months: int = ...,

weeks: int = ...,

days: int = ...,

hours: float = ...,

minutes: float = ...,

seconds: float = ...,

milliseconds: float = ...,

microseconds: float = ...,

nanoseconds: int = ...,

)

A duration with both a date and time component.

Deprecated since version 0.10.0: Use ItemizedDelta instead. DateTimeDelta normalizes its inputs separately for the date and time parts, losing the original fields. ItemizedDelta preserves the exact fields it was created with.

classmethod parse_iso(s: str, /) → DateTimeDelta

Parse the popular interpretation of the ISO 8601 duration format. Does not parse all possible ISO 8601 durations. See here for more information.

P4D        # 4 days
PT4H       # 4 hours
PT3M40.5S  # 3 minutes and 40.5 seconds
P1W11DT4H  # 1 week, 11 days, and 4 hours
-PT7H4M    # -7 hours and -4 minutes (-7:04:00)
+PT7H4M    # 7 hours and 4 minutes (7:04:00)

Inverse of format_iso()

>>> DateTimeDelta.parse_iso("-P1W11DT4H")
DateTimeDelta(-P1w11dT4h)

__abs__() → DateTimeDelta

The absolute value of the delta

>>> d = DateTimeDelta(weeks=1, days=-11, hours=4)
>>> abs(d)
DateTimeDelta("P1w11dT4h")

__add__(

other: DateTimeDelta | DateDelta | TimeDelta,

) → DateTimeDelta

Add two deltas together

>>> d = DateTimeDelta(weeks=1, days=11, hours=4)
>>> d + DateTimeDelta(months=2, days=3, minutes=90)
DateTimeDelta("P1m1w14dT5h30m")

__bool__() → bool

True if any field is non-zero

>>> bool(DateTimeDelta())
False
>>> bool(DateTimeDelta(minutes=1))
True

__eq__(other: object) → bool

Compare for equality

>>> d = DateTimeDelta(
...     weeks=1,
...     days=23,
...     hours=4,
... )
>>> d == DateTimeDelta(
...     weeks=1,
...     days=23,
...     minutes=4 * 60,  # normalized
... )
True
>>> d == DateTimeDelta(
...     weeks=4,
...     days=2,  # days/weeks are normalized
...     hours=4,
... )
True
>>> d == DateTimeDelta(
...     months=1,  # months/days cannot be compared directly
...     hours=4,
... )
False

__mul__(other: int) → DateTimeDelta

Multiply by a number

>>> d = DateTimeDelta(weeks=1, days=11, hours=4)
>>> d * 2
DateTimeDelta("P2w22dT8h")

__neg__() → DateTimeDelta

Negate the delta

>>> d = DateTimeDelta(days=11, hours=4)
>>> -d
DateTimeDelta(-P11dT4h)

__sub__(

other: DateTimeDelta | TimeDelta | DateDelta,

) → DateTimeDelta

Subtract two deltas

>>> d = DateTimeDelta(weeks=1, days=11, hours=4)
>>> d - DateTimeDelta(months=2, days=3, minutes=90)
DateTimeDelta(-P2m1w8dT2h30m)

date_part() → DateDelta

The date part of the delta

Deprecated since version 0.10.0.

format_iso() → str

Format as the popular interpretation of the ISO 8601 duration format. May not strictly adhere to (all versions of) the standard. See here for more information.

Inverse of parse_iso().

The format is:

P(nY)(nM)(nD)T(nH)(nM)(nS)

>>> d = DateTimeDelta(
...     weeks=1,
...     days=11,
...     hours=4,
...     milliseconds=12,
... )
>>> d.format_iso()
'P1W11DT4H0.012S'

in_months_days_secs_nanos() → tuple[int, int, int, int]

Convert to a tuple of (months, days, seconds, nanoseconds)

>>> d = DateTimeDelta(weeks=1, days=11, hours=4, microseconds=2)
>>> d.in_months_days_secs_nanos()
(0, 18, 14_400, 2000)

time_part() → TimeDelta

The time part of the delta

ZERO: ClassVar[DateTimeDelta] = DateTimeDelta("P0d")

A delta of zero