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