Dates and time

What it is and why it exists

Date-and-time data answers several different questions. An instant identifies one point on the timeline. Civil time supplies human calendar fields such as 2026-11-01 01:30, while a time zone supplies the rules that relate those fields to the timeline.

A duration answers how much time elapsed. Calendar arithmetic answers a different question, such as “the same local time tomorrow” or “the last day of next month.” These meanings coincide on ordinary days, which is why a design can look correct until a month end or clock transition reaches production.

The Unix epoch gives timestamp systems a common numeric origin. A count since that origin can identify an instant when its unit and time scale are known. The number does not remember the source time zone, the calendar wording entered by a user, or whether a schedule should retain local wall time when rules change.

You meet these distinctions in audit logs, booking systems, token expiry, billing periods, recurring jobs, age checks, telemetry, and user interfaces. A payment already made usually needs an instant. A birthday usually needs a calendar date without any time or zone.

A store opening every day at 09:00 needs local clock fields and a named zone. A request that must time out after five seconds needs a duration and a monotonic clock. One generic timestamp field cannot state all four contracts.

Name the domain value before choosing a representation:

This separation prevents lossy round trips. If a birthday becomes UTC midnight, displaying it west of UTC may produce the previous date. If a New York appointment keeps only -04:00, the value cannot apply winter rules or later time-zone database changes.

Formatting is straightforward compared with deciding which context owns the conversion and what to do when local fields are ambiguous or invalid. That policy belongs in the data contract, not in whichever helper happens to parse the value.

How it works

Instants and civil fields

An instant has no inherent year, month, hour, or weekday. Those are projections through a calendar and zone rule set. UTC is a useful projection with zero offset, but a UTC rendering is still a rendering of the instant rather than extra state inside it.

Civil time runs in the other direction. Fields such as year, month, day, hour, and minute describe what a clock and calendar show. To resolve them to an instant, you also need a calendar, a named zone or fixed offset, and sometimes a choice for a transition edge.

The two directions have different behavior:

Projecting an instant into a zone produces one result because the instant fixes which rule applies. Resolving local fields may produce zero, one, or two candidate instants. An API that exposes only local_time and zone but no resolution policy has left a business decision implicit.

Offsets and named zones

An offset such as +08:00 is one numeric relationship to UTC. It is enough to identify an instant when attached to complete local date-time fields. It does not describe past or future changes.

A named IANA zone such as Europe/Paris or America/New_York identifies a maintained history and rule set. Its offset depends on the instant being considered. Governments can change these rules, so deployed applications also depend on a time-zone database version.

Abbreviations such as CST are poor interchange identifiers. The same letters are used for different zones, and a short label may change seasonally. Use an IANA identifier for regional rules and an explicit numeric offset in an instant-bearing wire value.

Daylight saving time causes some rule changes. Historical offset changes and government decisions create transitions too. Code should reason about zone rules rather than assuming every transition follows a familiar one-hour seasonal pattern.

Gaps, overlaps, and fold

When clocks move forward, a range of local times is skipped. A local value inside that gap has no matching instant. When clocks move backward, a range repeats and each local value has two matching instants.

Python’s zoneinfo.ZoneInfo applies IANA rules to aware datetime objects. During an overlap, datetime.fold selects the pre-transition offset with 0 or the post-transition offset with 1. The flag matters only where the two interpretations differ.

Attaching ZoneInfo with the constructor or replace(tzinfo=...) does not validate that local fields exist. Python will create an aware object for a gap as well. If input begins as civil fields, validation requires a stated gap policy and a round trip through UTC or a scheduling library that exposes resolution directly.

Aware and naive values

Python calls a datetime aware when it has usable offset information; otherwise it is naive. A naive value does not carry a reliable promise that it means UTC, host-local time, or an unfinished civil value. That meaning exists only in surrounding code and is easily lost.

Use datetime.now(UTC) for a current UTC instant rather than datetime.utcnow(), which returns a naive result and is deprecated. Parse external instants into aware values at the boundary. Keep calendar-only values as date, and keep unresolved local schedules in a structure whose zone and policy are explicit.

replace(tzinfo=zone) relabels existing fields. It does not move an instant from one zone to another. astimezone(zone) preserves the instant and changes the projected fields, so the two operations are not interchangeable.

Durations and calendar arithmetic

An elapsed duration can be represented in seconds, nanoseconds, or a timedelta, subject to the precision the system needs. To add exactly 24 elapsed hours across a regional clock change, do timeline arithmetic in UTC and then project the result into the display zone.

Calendar arithmetic operates on fields and rules. “Tomorrow at noon” advances the local date and retains noon, even if only 23 or 25 hours pass on the timeline. “One month later” also needs an overflow rule because the target month may not contain the original day number.

Python arithmetic has a sharp same-zone rule. Adding a timedelta to an aware local datetime performs field arithmetic with the same tzinfo; subtracting two aware values that share that exact tzinfo ignores their offsets. Convert both endpoints to UTC or subtract their timestamps when the requirement is actual elapsed time.

Do not use wall-clock readings for an in-process timeout. Network synchronization or an operator can adjust system time, so successive UTC readings may jump. time.monotonic() cannot move backward and has no civil meaning, which is exactly what interval measurement needs.

Storage and boundaries

For recorded events, a documented RFC 3339 profile with an explicit, known offset or a documented integer epoch unit can cross a service boundary. Validate the grammar, range, precision, and unit. A bare integer called timestamp invites seconds-versus-milliseconds mistakes.

Store a named zone separately when later behavior depends on regional rules. A calendar service may need the original local fields, the IANA zone, the chosen overlap or gap policy, and the resolved instant. Keeping the instant as well supports ordering and audit without discarding scheduling intent.

Formatting belongs at the presentation edge. Supply the locale and zone explicitly rather than inheriting host defaults. Formatted output is for people; it is usually not a stable interchange format and should not be parsed back into domain data.

Database types differ. Some preserve an instant, some preserve fields without a zone, and names such as timestamp are product-specific. Read the database’s exact type contract and driver conversion behavior before mapping it to a language type.

Examples

The examples use Python 3.14’s standard datetime, zoneinfo, and time modules. Every output below was produced with Python 3.14.3 and the local IANA time-zone data.

Projecting one instant

The release value has an explicit UTC offset, so it identifies one instant. Each astimezone() call preserves that instant and changes only its civil projection.

New York’s 01:30 is the first occurrence on the day its clock moves back, so fold is 0. Shanghai has no overlap at that instant. Both lines still correspond to epoch second 1793511000.

This direction is deterministic for the loaded rule set: start with an instant, then project. The inverse needs a policy because New York will show 01:30 again one elapsed hour later.

Resolving a repeated local time

The next program constructs both interpretations of the same New York wall-clock fields. fold changes the selected offset and therefore the UTC instant.

from datetime import UTC, datetime
from zoneinfo import ZoneInfo


new_york = ZoneInfo("America/New_York")
first = datetime(2026, 11, 1, 1, 30, tzinfo=new_york, fold=0)
second = datetime(2026, 11, 1, 1, 30, tzinfo=new_york, fold=1)

for candidate in [first, second]:
    print(
        f"fold={candidate.fold} "
        f"offset={candidate.utcoffset()} "
        f"utc={candidate.astimezone(UTC).isoformat()}"
    )

print(f"same wall fields: {first.replace(tzinfo=None) == second.replace(tzinfo=None)}")
print(f"elapsed: {(second.timestamp() - first.timestamp()) / 3600:.0f} hour")

fold=0 offset=-1 day, 20:00:00 utc=2026-11-01T05:30:00+00:00
fold=1 offset=-1 day, 19:00:00 utc=2026-11-01T06:30:00+00:00
same wall fields: True
elapsed: 1 hour

The unusual negative timedelta display means UTC−04:00 and UTC−05:00. Removing tzinfo makes the fields compare equal, but their timestamps are one hour apart. A booking system must choose, reject, or ask rather than accepting whichever default the library supplies.

Do not infer fold from the hour alone. It is meaningful only with a date and zone whose rules create an overlap. Persist the resolved instant or the explicit choice when later reconstruction must return the same occurrence.

Calendar intent versus elapsed time

New York advances its clock on the morning of March 8 in this example. One operation keeps local noon on the next date; the other advances exactly 24 elapsed hours.

from datetime import UTC, datetime, timedelta
from zoneinfo import ZoneInfo


new_york = ZoneInfo("America/New_York")
start = datetime(2026, 3, 7, 12, 0, tzinfo=new_york)

# Calendar intent keeps 12:00; elapsed intent keeps 24 hours.
same_wall_time_tomorrow = start + timedelta(days=1)
after_twenty_four_hours = (
    start.astimezone(UTC) + timedelta(hours=24)
).astimezone(new_york)

print(f"start:    {start:%Y-%m-%d %H:%M %z}")
print(f"calendar: {same_wall_time_tomorrow:%Y-%m-%d %H:%M %z}")
print(f"elapsed:  {after_twenty_four_hours:%Y-%m-%d %H:%M %z}")
print(f"calendar seconds: {same_wall_time_tomorrow.timestamp() - start.timestamp():.0f}")
print(f"elapsed seconds:  {after_twenty_four_hours.timestamp() - start.timestamp():.0f}")

start:    2026-03-07 12:00 -0500
calendar: 2026-03-08 12:00 -0400
elapsed:  2026-03-08 13:00 -0400
calendar seconds: 82800
elapsed seconds:  86400

The calendar result is 82,800 elapsed seconds later because the local clock skipped an hour. The elapsed result appears at 13:00, one wall-clock hour later than the starting hour. Neither result is generally correct; the requirement selects one.

The code uses timestamps for the elapsed comparison. Writing (after_twenty_four_hours - start).total_seconds() would report the same-zone wall-field difference instead, which is 25 hours for those displayed fields. That result answers a different question.

Building a monotonic deadline

A deadline can be stored as a reading on a monotonic clock. Injecting the clock gives the test exact readings without pretending that a calendar timestamp controls an interval.

import time


class SequenceClock:
    def __init__(self, readings):
        self._readings = iter(readings)

    def __call__(self):
        return next(self._readings)


def make_deadline(timeout_seconds, clock=time.monotonic):
    expires_at = clock() + timeout_seconds

    def remaining():
        return max(0.0, expires_at - clock())

    return remaining


# Injecting the clock keeps this deadline test deterministic.
clock = SequenceClock([100.0, 101.25, 106.0])
remaining = make_deadline(5.0, clock)

print(f"remaining: {remaining():.2f}")
print(f"remaining: {remaining():.2f}")

remaining: 3.75
remaining: 0.00

The numeric readings cannot be converted to dates and should not be serialized for another process as universal timestamps. They are meaningful only for differences measured by a compatible clock in the current runtime. That narrow contract prevents calendar corrections from extending or shortening the timeout.

The max() clamp makes an expired budget report zero rather than a negative value. Real wait loops must still pass the current remaining budget to each blocking operation and stop when it reaches zero.

Pitfalls

Treating naive values as UTC

Fix: require an explicit offset for instant-bearing input and convert it to an aware value at the boundary. Model unresolved civil input separately; never use a comment or variable name as its only time-zone contract.

Relabeling instead of converting

Fix: use astimezone() to preserve an existing instant. Use replace(tzinfo=...) only when the fields are intentionally being resolved as local civil time, followed by gap and overlap handling.

Storing an offset as a zone

Fix: store the IANA zone identifier with the recurrence fields and define how rule-database updates affect future occurrences. Keep an explicit offset on resolved wire timestamps so each transmitted instant remains unambiguous.

Letting the library choose a transition policy

Fix: detect zero or two candidates by round-tripping through UTC, then apply a named product policy: reject, shift forward, choose earlier, choose later, or ask the user. Test real transitions in every supported scheduling zone.

Mixing calendar and elapsed arithmetic

Fix: put the semantic choice in the operation name and tests, such as expires_after_hours or next_local_occurrence. Assert both the resulting local fields and the timeline difference at transitions, month ends, leap days, and reverse moves.

Timing with the wall clock

Fix: use time.monotonic() or time.monotonic_ns() for elapsed work and deadlines. Record a separate UTC instant when logs need a civil timestamp; do not convert monotonic readings into dates.

Further reading

• Python datetime documentation
• Python zoneinfo documentation
• Python time.monotonic() documentation
• IANA time zone database theory
• RFC 3339: Date and Time on the Internet