Pylerno
English

Dates and times

Distinguish a calendar date, an instant, and an elapsed duration.

On this page

The concept

date represents a calendar day. datetime adds a time, and timedelta represents a duration. Adding a timedelta to a date handles calendar boundaries automatically. strptime interprets text using a specified format, while isoformat gives an explicit machine-friendly representation.

A timezone-aware datetime identifies its time-zone context. UTC is useful for recording instants consistently. Do not mix naive and aware timestamps without a policy. Measuring execution duration is a separate task: perf_counter is suitable for elapsed runtime, not for storing a historical event date.

Worked example

python
from datetime import UTC, date, datetime, timedelta

start = date(2026, 1, 28)
print("Next week:", start + timedelta(days=7))
parsed = datetime.strptime("2026-02-20", "%Y-%m-%d")
print("Parsed date:", parsed.date())
event = datetime(2026, 1, 15, 9, 30, tzinfo=UTC)
print(event.isoformat())
print((date(2026, 2, 1) - start).days)

Trace the result

  1. Adding seven days crosses from January into February without manual month arithmetic.
  2. strptime parses the fixed input into a datetime and date extracts its calendar portion.
  3. The fixed aware event keeps output reproducible; subtracting dates produces a timedelta whose days field is inspected.
text
Next week: 2026-02-04
Parsed date: 2026-02-20
2026-01-15T09:30:00+00:00
4
Line-by-line walkthrough

Line 1: from datetime import UTC, date, datetime, timedelta

Import UTC, date, datetime, timedelta from datetime. This supplies calendar dates, timestamps, and durations. The caller can now use the imported names directly.

Line 3: start = date(2026, 1, 28)

Evaluate date(2026, 1, 28), then bind or update start with the result. The call finishes before its return value is bound; a failed call does not produce a successful assignment. Assignment itself does not imply a deep copy.

Line 4: print("Next week:", start + timedelta(days=7))

Evaluate the print arguments from the current state and display them. sep controls separators and end controls the ending when those options are provided. Displaying a value does not return that value from the surrounding function.

Line 5: parsed = datetime.strptime("2026-02-20", "%Y-%m-%d")

Evaluate datetime.strptime('2026-02-20', '%Y-%m-%d'), then bind or update parsed with the result. The call finishes before its return value is bound; a failed call does not produce a successful assignment. Assignment itself does not imply a deep copy.

Line 6: print("Parsed date:", parsed.date())

Evaluate the print arguments from the current state and display them. sep controls separators and end controls the ending when those options are provided. Displaying a value does not return that value from the surrounding function.

Line 7: event = datetime(2026, 1, 15, 9, 30, tzinfo=UTC)

Evaluate datetime(2026, 1, 15, 9, 30, tzinfo=UTC), then bind or update event with the result. The call finishes before its return value is bound; a failed call does not produce a successful assignment. Assignment itself does not imply a deep copy.

Line 8: print(event.isoformat())

Evaluate the print arguments from the current state and display them. sep controls separators and end controls the ending when those options are provided. Displaying a value does not return that value from the surrounding function.

Line 9: print((date(2026, 2, 1) - start).days)

Evaluate the print arguments from the current state and display them. sep controls separators and end controls the ending when those options are provided. Displaying a value does not return that value from the surrounding function.

Common mistake

A local calendar day around daylight-saving transitions is not always a fixed 24-hour elapsed interval. Choose the model appropriate to the question.

Check your understanding

What does this program print?

python
from datetime import date
print((date(2024, 3, 1) - date(2024, 2, 28)).days)
Choose one answer

Search documentation

Share this page