TimeDelta

class whenever.TimeDelta(iso_string: str, /)[source]
class whenever.TimeDelta(py_timedelta: timedelta, /)
class whenever.TimeDelta(
*,
weeks: float = 0,
days: float = 0,
hours: float = 0,
minutes: float = 0,
seconds: float = 0,
milliseconds: float = 0,
microseconds: float = 0,
nanoseconds: int = 0,
days_assumed_24h_ok: bool = UNSET,
)

A delta consisting of a precise time: hours, minutes, (nano)seconds. For deltas including months or days, use ItemizedDelta, or ItemizedDateDelta for date-only deltas.

The inputs are normalized, so 90 minutes becomes 1 hour and 30 minutes, for example. A float input is multiplied into nanoseconds in double precision, then truncated toward zero: seconds=1.5e-9 is 1 nanosecond.

>>> d = TimeDelta(hours=1, minutes=90)
TimeDelta("PT2h30m")
>>> d.total("minutes")
150.0

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

>>> TimeDelta("PT2h30m")
TimeDelta("PT2h30m")
>>> from datetime import timedelta
>>> TimeDelta(timedelta(hours=2, minutes=30))
TimeDelta("PT2h30m")

TimeDelta can be added to or subtracted from datetime types to shift them by an exact amount of time:

>>> Instant("2022-10-24 00:00Z") + TimeDelta(hours=3)
Instant("2022-10-24 03:00:00Z")

Note

A shorter way to instantiate a timedelta is to use the helper functions hours(), minutes(), etc.

classmethod parse_iso(s: str, /) → TimeDelta[source]

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()

>>> TimeDelta.parse_iso("PT1H80M")
TimeDelta("PT2h20m")

Note

Any duration with a date part is considered invalid. PT0S is valid, but P0D is not.

__abs__() → TimeDelta[source]

The absolute value

>>> d = TimeDelta(hours=-1, minutes=-30)
>>> abs(d)
TimeDelta("PT1h30m")
__add__(other: TimeDelta, /) → TimeDelta[source]
__add__(other: Instant, /) → Instant
__add__(other: PlainDateTime, /) → PlainDateTime
__add__(other: OffsetDateTime, /) → OffsetDateTime
__add__(other: ZonedDateTime, /) → ZonedDateTime

Add two deltas together, or shift a datetime by this delta

>>> d = TimeDelta(hours=1, minutes=30)
>>> d + TimeDelta(minutes=30)
TimeDelta("PT2h")
>>> d + Instant.from_utc(2022, 10, 24)
Instant("2022-10-24 01:30:00Z")

Shifting a PlainDateTime emits NaiveArithmeticWarning and an OffsetDateTime StaleOffsetWarning, as their add() methods do; use those to pass the escape.

__bool__() → bool[source]

True if the value is non-zero

>>> bool(TimeDelta())
False
>>> bool(TimeDelta(minutes=1))
True
__eq__(other: object, /) → bool[source]

Compare for equality

>>> d = TimeDelta(hours=1, minutes=30)
>>> d == TimeDelta(minutes=90)
True
>>> d == TimeDelta(hours=2)
False
__floordiv__(other: TimeDelta, /) → int[source]

Floor division by another delta

>>> d = TimeDelta(hours=1, minutes=39)
>>> d // TimeDelta(minutes=15)
6
__ge__(other: TimeDelta, /) → bool[source]

Return self>=value.

__gt__(other: TimeDelta, /) → bool[source]

Return self>value.

__le__(other: TimeDelta, /) → bool[source]

Return self<=value.

__lt__(other: TimeDelta, /) → bool[source]

Return self<value.

__mod__(other: TimeDelta, /) → TimeDelta[source]

Modulo by another delta

>>> d = TimeDelta(hours=1, minutes=39)
>>> d % TimeDelta(minutes=15)
TimeDelta("PT9m")
__mul__(other: float, /) → TimeDelta[source]

Multiply by a number, as d * 2 or 2 * d

The result is rounded half-even to the nearest nanosecond; an integer operand is exact, a float operand carries float precision. Float keywords, as in TimeDelta(seconds=1.5e-9), are truncated toward zero instead.

>>> d = TimeDelta(hours=1, minutes=30)
>>> d * 2.5
TimeDelta("PT3h45m")
__neg__() → TimeDelta[source]

Negate the value

>>> d = TimeDelta(hours=1, minutes=30)
>>> -d
TimeDelta("-PT1h30m")
__pos__() → TimeDelta[source]

Return the value unchanged

>>> d = TimeDelta(hours=1, minutes=30)
>>> +d
TimeDelta("PT1h30m")
__str__() → str[source]

Return str(self).

__sub__(other: TimeDelta, /) → TimeDelta[source]

Subtract two deltas

>>> d = TimeDelta(hours=1, minutes=30)
>>> d - TimeDelta(minutes=30)
TimeDelta("PT1h")
__truediv__(other: float, /) → TimeDelta[source]
__truediv__(other: TimeDelta, /) → float

Divide by a number or another delta

Dividing by a number rounds half-even to the nearest nanosecond; an integer operand is exact, a float operand carries float precision. Dividing by another delta gives a float.

>>> d = TimeDelta(hours=1, minutes=30)
>>> d / 2.5
TimeDelta("PT36m")
>>> d / TimeDelta(minutes=30)
3.0
add(delta: TimeDelta, /) → TimeDelta[source]
add(
*,
weeks: float = ...,
days: float = ...,
hours: float = ...,
minutes: float = ...,
seconds: float = ...,
milliseconds: float = ...,
microseconds: float = ...,
nanoseconds: int = ...,
days_assumed_24h_ok: bool = ...,
) → TimeDelta

Add time to this delta, returning a new delta.

Days and weeks are treated as exact 24-hour and 168-hour units, which emits a DaysAssumed24HoursWarning unless days_assumed_24h_ok=True.

>>> TimeDelta(hours=1).add(minutes=30)
TimeDelta("PT1h30m")
>>> TimeDelta(hours=1).add(TimeDelta(minutes=30))
TimeDelta("PT1h30m")
format_iso() → str[source]

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().

>>> TimeDelta(hours=1, minutes=30).format_iso()
'PT1H30M'
in_units(
units: Sequence[DeltaUnitStr],
/,
*,
round_mode: RoundModeStr = 'trunc',
round_increment: int = 1,
relative_to: ZonedDateTime | PlainDateTime | OffsetDateTime = ...,
days_assumed_24h_ok: bool = ...,
naive_arithmetic_ok: bool = ...,
stale_offset_ok: bool = ...,
) → ItemizedDelta[source]

Convert to an ItemizedDelta in the given units.

>>> d = TimeDelta(hours=2, minutes=30, seconds=23, milliseconds=500)
>>> d.in_units(['minutes', 'seconds'])
ItemizedDelta("PT150m23s")
>>> hrs, mins = d.in_units(('hours', 'minutes'), round_mode='ceil').values()
(2, 31)
Parameters:
  • units – The units of the result, largest first.

  • round_mode – The rounding mode for the smallest unit in units, as on round().

  • round_increment – The rounding increment for that unit.

  • relative_to – The reference the calendar units are resolved against. Required for years and months, whose length depends on the date. Without it, days and weeks are taken as 24 and 168 hours. A ZonedDateTime emits no warning. A PlainDateTime ignores time zone transitions, and emits NaiveArithmeticWarning when the units include a calendar unit. An OffsetDateTime holds its offset fixed for the whole calculation, and emits StaleOffsetWarning when the units include a calendar unit.

  • days_assumed_24h_ok – Accepts the DaysAssumed24HoursWarning of days or weeks without a reference.

  • naive_arithmetic_ok – Accepts the NaiveArithmeticWarning of a PlainDateTime reference.

  • stale_offset_ok – Accepts the StaleOffsetWarning of an OffsetDateTime reference.

round(
unit: Literal['week', 'day', 'hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond'] | TimeDelta = 'second',
/,
*,
increment: int = ...,
mode: RoundModeStr = 'half_even',
days_assumed_24h_ok: bool = ...,
) → TimeDelta[source]

Round the delta to the specified unit and increment, or to a multiple of another TimeDelta. Different rounding modes are available.

>>> t = TimeDelta(seconds=12345)
>>> t.round("minute")
TimeDelta("PT3h26m")
>>> t.round("second", increment=10, mode="floor")
TimeDelta("PT3h25m40s")
>>> t.round(TimeDelta(minutes=15))
TimeDelta("PT3h30m")
>>> TimeDelta(hours=50).round("day", days_assumed_24h_ok=True)
TimeDelta("PT48h")

Warning

"day" and "week" are exact 24-hour and 168-hour units here, which emits DaysAssumed24HoursWarning. Pass days_assumed_24h_ok=True when that is intentional. A TimeDelta unit claims no calendar and never warns.

subtract(delta: TimeDelta, /) → TimeDelta[source]
subtract(
*,
weeks: float = ...,
days: float = ...,
hours: float = ...,
minutes: float = ...,
seconds: float = ...,
milliseconds: float = ...,
microseconds: float = ...,
nanoseconds: int = ...,
days_assumed_24h_ok: bool = ...,
) → TimeDelta

Subtract time from this delta, returning a new delta.

Days and weeks are treated as exact 24-hour and 168-hour units, which emits a DaysAssumed24HoursWarning unless days_assumed_24h_ok=True.

>>> TimeDelta(hours=1).subtract(minutes=30)
TimeDelta("PT30m")
to_stdlib() → timedelta[source]

Convert to a timedelta

>>> d = TimeDelta(hours=1, minutes=30)
>>> d.to_stdlib()
datetime.timedelta(seconds=5400)

Note

Nanoseconds are floored to microseconds. If you need more control over rounding, use round() first.

total(
unit: Literal['years', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds', 'microseconds', 'nanoseconds'],
/,
*,
relative_to: ZonedDateTime | PlainDateTime | OffsetDateTime = ...,
days_assumed_24h_ok: bool = ...,
naive_arithmetic_ok: bool = ...,
stale_offset_ok: bool = ...,
) → float | int[source]

The total duration in the given unit.

>>> d = TimeDelta(hours=1, minutes=30)
>>> d.total('minutes')
90.0
Parameters:
MAX: ClassVar[TimeDelta] = TimeDelta("PT87831216h")

The maximum possible value of this type.

MIN: ClassVar[TimeDelta] = TimeDelta("-PT87831216h")

The minimum possible value of this type.

ZERO: ClassVar[TimeDelta] = TimeDelta("PT0s")

A delta of zero

whenever.hours(i: float, /) → TimeDelta[source]

Create a TimeDelta with the given number of hours. hours(1) == TimeDelta(hours=1)

whenever.minutes(i: float, /) → TimeDelta[source]

Create a TimeDelta with the given number of minutes. minutes(1) == TimeDelta(minutes=1)

whenever.seconds(i: float, /) → TimeDelta[source]

Create a TimeDelta with the given number of seconds. seconds(1) == TimeDelta(seconds=1)

whenever.milliseconds(i: float, /) → TimeDelta[source]

Create a TimeDelta with the given number of milliseconds. milliseconds(1) == TimeDelta(milliseconds=1)

whenever.microseconds(i: float, /) → TimeDelta[source]

Create a TimeDelta with the given number of microseconds. microseconds(1) == TimeDelta(microseconds=1)

whenever.nanoseconds(i: int, /) → TimeDelta[source]

Create a TimeDelta with the given number of nanoseconds. nanoseconds(1) == TimeDelta(nanoseconds=1)