Glossary

The words whenever uses, one entry per term. Each entry settles the name, lists under Also called what other libraries and standards call the same thing, and links to the page that explains the concept.

exact time

A single moment on the global timeline, independent of any time zone. Instant, OffsetDateTime, and ZonedDateTime represent one. Also called absolute time and UTC time. See Exact time vs local time.

local time

A clock and calendar reading as seen in a particular place. PlainDateTime, Date, and Time represent one. Also called civil time and wall-clock time. See Exact time vs local time.

unit

A span of time that values round to and quantities count in: an exact unit or a calendar unit. Its name is singular where you round to an hour (round("hour"), start_of(), end_of(), format_iso(unit=), timestamp(unit=)) and plural where you count the total of minutes (total("minutes"), in_units=["hours", "minutes"]).

exact units

Units of fixed duration: hours, minutes, seconds, and smaller. See Date-time arithmetic.

calendar units

Units defined by the calendar and the local clock, with no fixed duration: days, weeks, months, and years. See Date-time arithmetic.

DST-safe arithmetic

The industry convention that exact units add elapsed time and calendar units keep the local date and clock time, so a result is right on either side of a time zone transition. RFC 5545 states the rule, and modern date-time libraries (Temporal, java.time, NodaTime) follow it, as ZonedDateTime does. See Date-time arithmetic.

naive arithmetic

Exact-unit arithmetic on a local time, which has no time zone and so ignores every transition: two hours added to a PlainDateTime move its clock two hours whatever the region’s clocks did. Flagged by NaiveArithmeticWarning, accepted with naive_arithmetic_ok=. Naive alone describes a stdlib datetime without a tzinfo; a whenever value is local, never naive. See PlainDateTime.

clamping

A shift by years or months whose result names a day the target month lacks lands on that month’s last day: January 31 plus one month is February 29 or 28, and February 29 plus one year is February 28. Also called truncation and constrain. See Calendar units.

rounding increment

The step a value is rounded to: a count of the unit, passed as increment=, or a TimeDelta passed as the unit itself. On a datetime or a Time it must divide a 24-hour day evenly. Also called quantum, step, granularity, and resolution. See Rounding and boundaries.

strict equality

Equality that also compares what == deliberately ignores: the argument’s type, the offset, the time zone, or a component given explicitly as zero. Provided by strict_eq() on exactly the types whose == ignores something. Also called exact equality. See Comparison and equality.

timestamp

A count of whole units since the UNIX epoch (1970-01-01 00:00 UTC): seconds by default, or milliseconds, microseconds, or nanoseconds via unit=. Floored at the unit, so it labels the bucket containing the instant. An ISO 8601 string is not a timestamp. Also called UNIX time, epoch time, and POSIX time. See To and from timestamps.

ISO 8601 string

The text form of a value, as produced by format_iso() and accepted by parse_iso(). “ISO 8601 format” names the format itself. Also called ISO timestamp and ISO datetime; ISO string is the short form. See ISO 8601.

time zone

A region’s rules for its offset from UTC, including any daylight saving changes. Named by a time zone ID, or taken from the system. Also called timezone and zone. See Time zones.

time zone ID

The IANA name of a time zone’s rules, such as Europe/Paris. Exposed as tz_id and written in brackets in an ISO 8601 string. The system time zone may lack one. Also called IANA identifier, time zone name, time zone key, and tz. See Working with the time zone database.

named time zone

A time zone identified by a time zone ID, with the rules the database records for it. The system time zone may lack an ID, and a fixed offset names no rules, so neither is one. The ID is the name: time zone ID is the string, named time zone the rules it names. Also called IANA time zone. See Working with the time zone database.

time zone search path

The ordered directories in which time zone IDs are looked up. Read with get_tzpath(), which returns a snapshot; set with reset_tzpath(), or initially by PYTHONTZPATH. The tzdata package is a fallback after the path, not part of it. Also called tzpath, TZPATH, time zone path, and zoneinfo path. See Working with the time zone database.

system time zone

The time zone the operating system is configured with. Requested with SYSTEM_TZ wherever a time zone ID is accepted. Each call resolves it and stores the result in the returned value, which keeps that time zone for good; reset_system_tz() changes only what later calls resolve to. It may have no time zone ID. Also called local time zone, local zone, machine time zone, and OS time zone. See The system time zone.

ambiguity

The umbrella for a repeated or skipped local time: a local time that a time zone maps to two instants or to none. Ambiguous is allowed only when both cases are meant, unambiguous when neither applies; one case takes its own headword. Resolved by disambiguation. See Ambiguity.

repeated local time

A local time that occurs twice in a time zone because the clock moved backward. Resolved by a disambiguation policy; is_repeated() on a ZonedDateTime reports one. The interval of repeated local times around one transition is a fold; the word names the interval, never one time in it. Also called ambiguous time and, outside these docs, fold. See Repeated and skipped local times.

skipped local time

A local time that does not occur in a time zone because the clock moved forward. Resolved by a disambiguation policy. The interval of skipped local times around one transition is a gap; the word names the interval, never one time in it. Also called non-existent time and, outside these docs, gap. See Repeated and skipped local times.

disambiguation

The policy that picks the instant for a repeated or skipped local time in a named time zone: "compatible", "earlier", "later", or "raise". Passed as disambiguation=; when omitted, "compatible" applies with an ImplicitDisambiguationWarning. Also called disambiguate, ambiguity policy, and fold handling. See Repeated and skipped local times.

offset mismatch

A numeric offset in the input that identifies no occurrence of the written local time in the named time zone. Resolved by offset_mismatch=, before disambiguation can apply. A ZonedDateTime pickle loaded under changed time zone rules is one too; unpickling resolves it as keep_instant and emits PickleOffsetMismatchWarning. Also called offset conflict, offset disagreement, and pickle reconciliation. See The complete resolution flow and Pickling and copying.

offset-preserving resolution

How replace() and calendar arithmetic on a ZonedDateTime resolve their result: the current offset is kept when it is still valid for the new local time, whatever the disambiguation policy says, and the policy applies otherwise. Also called keep offset and sticky offset. See Offset-preserving resolution.

stale offset

The offset an OffsetDateTime carries after an operation moved the value: still the observed offset, but no longer certain to be the one the source time zone would apply. Flagged by StaleOffsetWarning. Also called wrong offset and outdated offset. See OffsetDateTime.

call-local escape

A keyword argument that accepts one flagged risk for one call, such as naive_arithmetic_ok=True. Each belongs to one warning, whose message names it. Also called escape hatch, suppression flag, opt-out, override, and per-method kwarg. See Handling warnings.

compatibility shim

A deprecated spelling kept until 1.0: it does what its replacement does and emits WheneverDeprecationWarning. The changelog’s migration table lists each one. Also called wrapper, alias, and legacy path.

time patch

A test-only override of the current time as Whenever sees it, created by patch_current_time() and driven through its TimePatch handle. Either frozen (holds one instant) or ticking (advances from it). Also called mocked time and fake clock; frozen time names only the frozen kind. See Testing.

pattern

A string of specifiers and literal text that format() writes and parse() reads, passed as pattern=. The canonical full pattern is YYYY-MM-DD HH:mm:ss. Also called format string, format, and custom format. See Pattern format.

specifier

A run of one letter in a pattern that stands for one value, such as HH or MMM. Two specifiers cannot set the same value. Also called pattern letter, token, directive, and format code. See Pattern format.

optional seconds

The bracketed group after the minutes in a pattern, [ss] or [:ss] with an optional fraction, written only when seconds or nanoseconds are nonzero. Brackets have no other use in a pattern. Also called optional group, bracket group, and seconds tail. See Pattern format.

24-hour clock

Hours 0 through 23, written with the H/HH specifiers. Also called 24-hour format and 24-hour time. See Pattern format.

12-hour clock

Hours 1 through 12 together with an AM/PM specifier, written with i/ii and a/aa. A pattern with i/ii but no AM/PM specifier warns; an AM/PM specifier without i/ii doesn’t. Also called 12-hour format, 12-hour time, and AM/PM time. See Pattern format.

itemized delta

A delta that keeps every component as it was given: ItemizedDelta and ItemizedDateDelta. Ninety minutes stays ninety minutes. Also called unnormalized delta, period, and span. See Normalized or “itemized”.

normalized delta

A delta reduced to one exact duration, whatever components built it: TimeDelta. Ninety minutes and an hour and a half are the same value. Also called duration. Here a duration is the quantity a delta measures, not a type. See Normalized or “itemized”.

component

One unit’s value in an itemized delta, such as months or nanoseconds. A component is present when the delta was given it, an explicit zero included; == ignores presence, iteration and strict_eq() do not. Also called field and part; a present component is elsewhere set. The date part and time part of an itemized delta are its calendar and exact components as two groups, what date_and_time_parts() splits, never one component. See Normalized or “itemized”.

balancing

Redistributing a delta over a chosen set of units with in_units(), such as 150 minutes into 2 hours and 30 minutes. Calendar units need a relative_to reference. Also called normalizing into units and rebalancing. See Convert into specific units.

component-wise composition

Adding or subtracting two itemized deltas by combining like components, as +, -, add(), and subtract() do. With years or months, the result can land on a different day than the deltas applied in turn, which MonthCompositionWarning flags. Also called field-wise composition and literal addition. See Addition and subtraction.

partial type

A type that holds part of a datetime: Date, Time, YearMonth, MonthDay, and IsoWeekDate. Partial is the short form. Also called smaller types, date-only types, and component types. See Partial types.

Rust extension

The compiled backend the default wheel ships, loaded when import whenever finds it. Backend names either of the two. Also called native binary, compiled core, and the extension. See Performance.

pure-Python backend

The fallback that loads when the Rust extension is absent, and the reference the Rust extension mirrors. Behaviour is the same; speed is not. Also called pure-Python version, pure-Python implementation, pure-Python option, and pure-Python fallback. The pure-Python wheel is the package artifact that contains only this backend. See How can I use the pure-Python backend?.