Time

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

final class whenever.Time(t: time, /)

final class whenever.Time(hour: int = 0, minute: int = 0, second: int = 0, *, nanosecond: int = 0)

Time of day without a date component.

>>> t = Time(12, 30, 0)
Time("12:30:00")

Can also be constructed from an ISO 8601 string:

>>> Time("12:30:00")
Time("12:30:00")

Or a standard library time:

>>> Time(time(12, 30, 0))
Time("12:30:00")

Note

When constructing from a time, the fold attribute and tzinfo are ignored.

Sub-second precision up to nanoseconds is supported:

>>> Time(12, 30, 0, nanosecond=1)
Time("12:30:00.000000001")

Times can be compared and sorted:

>>> Time(12, 30) > Time(8, 0)
True

classmethod from_py_time(t: time, /) → Time

Create from a time

>>> Time.from_py_time(time(12, 30, 0))
Time(12:30:00)

Deprecated since version 0.10.0: Use the constructor Time(t) instead.

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

Parse a time from a custom pattern string.

See Pattern format for details.

>>> Time.parse("14:30:05", format="hh:mm:ss")
Time(14:30:05)
>>> Time.parse("02:30 PM", format="ii:mm aa")
Time(14:30:00)

classmethod parse_iso(s: str, /) → Time

Create from the ISO 8601 time format

Inverse of format_iso()

>>> Time.parse_iso("12:30:00")
Time(12:30:00)

__eq__(other: object) → bool

Compare for equality

>>> t = Time(12, 30, 0)
>>> t == Time(12, 30, 0)
True
>>> t == Time(12, 30, 1)
False

__ge__(other: Time) → bool

Return self>=value.

__gt__(other: Time) → bool

Return self>value.

__le__(other: Time) → bool

Return self<=value.

__lt__(other: Time) → bool

Return self<value.

format(pattern: str, /) → str

Format as a custom pattern string.

See Pattern format for details.

>>> Time(14, 30, 5).format("hh:mm:ss")
'14:30:05'
>>> Time(14, 30).format("ii:mm aa")
'02:30 PM'

format_iso(

*,

unit: Literal['hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond', 'auto'] = 'auto',

basic: bool = False,

) → str

Format as the ISO 8601 time format.

Inverse of parse_iso().

>>> Time(12, 30, 0).format_iso(unit='millisecond')
'12:30:00.000'
>>> Time(4, 0, 59, nanosecond=40_000).format_iso(basic=True)
'040059.00004'

on(d: Date, /) → PlainDateTime

Combine a time with a date to create a datetime

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

Then, use methods like assume_utc() or assume_tz() to find the corresponding exact time:

>>> t.on(Date(2021, 1, 2)).assume_tz("America/New_York")
ExactDateTime("2021-01-02 12:30:00-05:00[America/New_York]")

py_time() → time

Convert to a standard library time

Deprecated since version 0.10.0: Use to_stdlib() instead.

replace(hour: int = ..., minute: int = ..., second: int = ..., nanosecond: int = ...) → Time

Create a new instance with the given fields replaced

>>> t = Time(12, 30, 0)
>>> d.replace(minute=3, nanosecond=4_000)
Time(12:03:00.000004)

round(

unit: Literal['hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond'] | TimeDelta = 'second',

/,

*,

increment: int = 1,

mode: RoundModeStr = 'half_even',

) → Time

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

>>> Time(12, 39, 59).round("minute", 15)
Time(12:45:00)
>>> Time(8, 9, 13).round("second", 5, mode="floor")
Time(08:09:10)
>>> Time(12, 39, 59).round(TimeDelta(minutes=15))
Time(12:45:00)

to_stdlib() → time

Convert to a standard library time

Note

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

MAX: ClassVar[Time] = Time("23:59:59.999999999")

The maximum time, just before midnight

MIDNIGHT: ClassVar[Time] = Time("00:00:00")

Alias for MIN

MIN: ClassVar[Time] = Time("00:00:00")

The minimum time, at midnight

NOON: ClassVar[Time] = Time("12:00:00")

The time at noon

property hour: int

The hour component of the time

>>> Time(12, 30, 0).hour
12

property minute: int

The minute component of the time

>>> Time(12, 30, 0).minute
30

property nanosecond: int

The nanosecond component of the time

>>> Time("12:30:00.003).nanosecond
3000000

property second: int

The second component of the time >>> Time(12, 30, 0).second 0