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, orItemizedDateDeltafor 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-9is 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")
TimeDeltacan 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.
PT0Sis valid, butP0Dis 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
PlainDateTimeemitsNaiveArithmeticWarningand anOffsetDateTimeStaleOffsetWarning, as theiradd()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
- __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 * 2or2 * dThe result is rounded half-even to the nearest nanosecond; an integer operand is exact, a
floatoperand carries float precision. Float keywords, as inTimeDelta(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")
- __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
floatoperand carries float precision. Dividing by another delta gives afloat.>>> 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 = ...,
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
DaysAssumed24HoursWarningunlessdays_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 = ...,
Convert to an
ItemizedDeltain 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 onround().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
ZonedDateTimeemits no warning. APlainDateTimeignores time zone transitions, and emitsNaiveArithmeticWarningwhen the units include a calendar unit. AnOffsetDateTimeholds its offset fixed for the whole calculation, and emitsStaleOffsetWarningwhen the units include a calendar unit.days_assumed_24h_ok – Accepts the
DaysAssumed24HoursWarningof days or weeks without a reference.naive_arithmetic_ok – Accepts the
NaiveArithmeticWarningof aPlainDateTimereference.stale_offset_ok – Accepts the
StaleOffsetWarningof anOffsetDateTimereference.
- round(
- unit: Literal['week', 'day', 'hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond'] | TimeDelta = 'second',
- /,
- *,
- increment: int = ...,
- mode: RoundModeStr = 'half_even',
- days_assumed_24h_ok: bool = ...,
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 emitsDaysAssumed24HoursWarning. Passdays_assumed_24h_ok=Truewhen that is intentional. ATimeDeltaunit 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 = ...,
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
DaysAssumed24HoursWarningunlessdays_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 = ...,
The total duration in the given unit.
>>> d = TimeDelta(hours=1, minutes=30) >>> d.total('minutes') 90.0
- Parameters:
unit – The unit to sum into.
"nanoseconds"gives anint, any other unit afloat.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
ZonedDateTimeemits no warning. APlainDateTimeignores time zone transitions, and emitsNaiveArithmeticWarningfor a calendar unit. AnOffsetDateTimeholds its offset fixed for the whole calculation, and emitsStaleOffsetWarningfor a calendar unit. An exact unit doesn’t use the reference.days_assumed_24h_ok – Accepts the
DaysAssumed24HoursWarningof a day or week total without a reference.naive_arithmetic_ok – Accepts the
NaiveArithmeticWarningof aPlainDateTimereference.stale_offset_ok – Accepts the
StaleOffsetWarningof anOffsetDateTimereference.
- whenever.hours(i: float, /) TimeDelta[source]¶
Create a
TimeDeltawith the given number of hours.hours(1) == TimeDelta(hours=1)
- whenever.minutes(i: float, /) TimeDelta[source]¶
Create a
TimeDeltawith the given number of minutes.minutes(1) == TimeDelta(minutes=1)
- whenever.seconds(i: float, /) TimeDelta[source]¶
Create a
TimeDeltawith the given number of seconds.seconds(1) == TimeDelta(seconds=1)
- whenever.milliseconds(i: float, /) TimeDelta[source]¶
Create a
TimeDeltawith the given number of milliseconds.milliseconds(1) == TimeDelta(milliseconds=1)