TimeDelta

final class whenever.TimeDelta(iso_string: str, /)[source]
final class whenever.TimeDelta(py_timedelta: timedelta, /)
final 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,
)

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

The inputs are normalized, so 90 minutes becomes 1 hour and 30 minutes, for example.

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

Note

Subclasses of timedelta are not accepted, because they often add additional state that cannot be represented.

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 from_py_timedelta(td: timedelta, /) → TimeDelta[source]

Create from a timedelta

>>> TimeDelta.from_py_timedelta(timedelta(seconds=5400))
TimeDelta("PT1h30m")

Deprecated since version 0.10.0: Use the constructor TimeDelta(td) instead.

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 two deltas together

>>> d = TimeDelta(hours=1, minutes=30)
>>> d + TimeDelta(minutes=30)
TimeDelta("PT2h")
__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 // time_delta(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

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

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'
__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

>>> d = TimeDelta(hours=1, minutes=30)
>>> d / 2.5
TimeDelta("PT36m")
>>> d / TimeDelta(minutes=30)
3.0

Note

Because TimeDelta is limited to nanosecond precision, the result of division may not be exact.

add(other: TimeDelta, /) → TimeDelta[source]
add(
*,
weeks: float = ...,
days: float = ...,
hours: float = ...,
minutes: float = ...,
seconds: float = ...,
milliseconds: float = ...,
microseconds: float = ...,
nanoseconds: int = ...,
) → 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 DaysNotAlways24HoursWarning.

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_days_of_24h() → float[source]

The total size in days (of exactly 24 hours each)

Note

Note that this may not be the same as days on the calendar, since some days have 23 or 25 hours due to daylight saving time.

Deprecated since version 0.10.0: Use total() with 'days' instead.

in_hours() → float[source]

The total size in hours

>>> d = TimeDelta(hours=1, minutes=30)
>>> d.in_hours()
1.5

Deprecated since version 0.10.0: Use total() with 'hours' instead.

in_hrs_mins_secs_nanos() → tuple[int, int, int, int][source]

Convert to a tuple of (hours, minutes, seconds, nanoseconds)

>>> d = TimeDelta(hours=1, minutes=30, microseconds=5_000_090)
>>> d.in_hrs_mins_secs_nanos()
(1, 30, 5, 90_000)

Deprecated since version 0.10.0: Use in_units() with ['hours', 'minutes', 'seconds', 'nanoseconds'] instead.

in_microseconds() → float[source]

The total size in microseconds

>>> d = TimeDelta(seconds=2, nanoseconds=50)
>>> d.in_microseconds()
2_000_000.05

Deprecated since version 0.10.0: Use total() with 'microseconds' instead.

in_milliseconds() → float[source]

The total size in milliseconds

>>> d = TimeDelta(seconds=2, microseconds=50)
>>> d.in_milliseconds()
2_000.05

Deprecated since version 0.10.0: Use total() with 'milliseconds' instead.

in_minutes() → float[source]

The total size in minutes

>>> d = TimeDelta(hours=1, minutes=30, seconds=30)
>>> d.in_minutes()
90.5

Deprecated since version 0.10.0: Use total() with 'minutes' instead.

in_nanoseconds() → int[source]

The total size in nanoseconds

>>> d = TimeDelta(seconds=2, nanoseconds=50)
>>> d.in_nanoseconds()
2_000_000_050

Deprecated since version 0.10.0: Use total() with 'nanoseconds' instead.

in_seconds() → float[source]

The total size in seconds

>>> d = TimeDelta(minutes=2, seconds=1, microseconds=500_000)
>>> d.in_seconds()
121.5

Deprecated since version 0.10.0: Use total() with 'seconds' instead.

in_units(
units: Sequence[TypeAliasForwardRef('DeltaUnitStr')],
/,
*,
round_mode: RoundModeStr = 'trunc',
round_increment: int = 1,
relative_to: ZonedDateTime | PlainDateTime | OffsetDateTime = ...,
) → ItemizedDelta[source]

Convert to a ItemizedDelta with the specified units

>>> d = TimeDelta(hours=2, minutes=30, seconds=23, milliseconds=500)
>>> d.in_units(['minutes', 'seconds'])
ItemizedDelta("PT150m24s")
>>> (hrs, mins) = d.in_units(('hours', 'minutes'), round_mode='ceil').values()
(2, 31)
Parameters:

  • units – A sequence of plural unit names, in descending order. Valid unit names are: weeks, days, hours, minutes, seconds, nanoseconds. years and months are also allowed if relative_to is provided.

  • round_mode – The rounding mode to use when rounding before conversion. See round() for details.

  • round_increment – The rounding increment to use when rounding before conversion. See round() for details.

  • relative_to –

    A reference datetime required when using calendar units (years, months, days, or weeks) to account for variable unit lengths.

py_timedelta() → timedelta[source]

Convert to a timedelta

Deprecated since version 0.10.0: Use to_stdlib() instead.

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

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

>>> t = TimeDelta(seconds=12345)
TimeDelta("PT3h25m45s")
>>> t.round("minute")
TimeDelta("PT3h26m")
>>> t.round("second", increment=10, mode="floor")
TimeDelta("PT3h25m40s")
>>> t.round(TimeDelta(minutes=15))
TimeDelta("PT3h30m")
subtract(other: TimeDelta, /) → TimeDelta[source]
subtract(
*,
weeks: float = ...,
days: float = ...,
hours: float = ...,
minutes: float = ...,
seconds: float = ...,
milliseconds: float = ...,
microseconds: float = ...,
nanoseconds: int = ...,
) → 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 DaysNotAlways24HoursWarning.

to_stdlib() → timedelta[source]

Convert to a timedelta

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

Note

Nanoseconds are truncated 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 = ...,
_warn_stacklevel: int = 2,
) → float | int[source]

The total size in the given unit, as a float (or int for nanoseconds)

For calendar units (years, months, weeks, days), a relative_to argument is required to determine the actual duration of each unit:

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

The maximum possible delta

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

The minimum possible delta

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)