---
myst:
html_meta:
description: >-
The vocabulary of whenever: one entry per term, the words other
libraries and standards use for it, and a link to the page that
explains the concept.
---
(glossary)=
# 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.
```{glossary}
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 {ref}`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 {ref}`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 {ref}`Date-time arithmetic `.
calendar units
Units defined by the calendar and the local clock, with no fixed duration:
days, weeks, months, and years.
See {ref}`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 {ref}`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 {ref}`arithmetic-plain`.
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 {ref}`arith-add-cal`.
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 {ref}`rounding`.
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 {doc}`guide/comparison`.
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 {ref}`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 {ref}`iso8601`.
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 {ref}`timezones-explained`.
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 {ref}`timezone-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 {ref}`timezone-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 {ref}`timezone-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 {ref}`systemtime`.
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 {ref}`ambiguity2`.
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 {ref}`ambiguity`.
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 {ref}`ambiguity`.
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 {ref}`ambiguity`.
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 {ref}`offset-mismatch` and {ref}`pickling`.
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 {ref}`offset-preserving`.
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 {ref}`offset-datetime-guidance`.
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 {ref}`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 {doc}`guide/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 {ref}`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 {ref}`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 {ref}`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 {ref}`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 {ref}`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 {ref}`delta-norm`.
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 {ref}`delta-norm`.
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 {ref}`delta-norm`.
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 {ref}`delta-in-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 {ref}`delta-add-sub`.
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 {ref}`partial-api`.
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 {doc}`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 {ref}`faq-pure-python`.
```