Python: Numbers, Dates & Times

Every pattern you'd Google - datetime, formatting, math, and more

Datetime Class Hierarchy

Python's datetime module contains a small set of classes organized in a clear inheritance tree. The key insight is that datetime is a subclass of date, so every datetime object is also a date. The abstract tzinfo base class provides the timezone interface, and its concrete subclass timezone handles fixed UTC offsets:

object
├── date
│   │   .year  .month  .day
│   │   .today()  .fromtimestamp()  .fromisoformat()
│   │   .weekday()  .isoformat()  .strftime()
│   │
│   └── datetime  (inherits from date)
│       │   .hour  .minute  .second  .microsecond  .tzinfo
│       │   .now()  .utcnow()  .combine()  .fromisoformat()
│       │   .timestamp()  .astimezone()  .replace()
│       │
│       │   ┌──────────────────────────────────┐
│       │   │  Naive:  dt.tzinfo is None       │
│       │   │  Aware:  dt.tzinfo is not None   │
│       │   │          dt.utcoffset() != None   │
│       │   └──────────────────────────────────┘
│       │
│       └── (no further subclasses in stdlib)
│
├── time
│       .hour  .minute  .second  .microsecond  .tzinfo
│       .fromisoformat()  .isoformat()  .strftime()
│       (represents a time-of-day, independent of any date)
│
├── timedelta
│       .days  .seconds  .microseconds
│       .total_seconds()
│       (represents a duration, the result of date/datetime subtraction)
│       Max: 999999999 days, 23:59:59.999999
│       Min: -999999999 days
│
└── tzinfo  (abstract base class)
    │   .utcoffset(dt)  .tzname(dt)  .dst(dt)
    │
    └── timezone  (concrete, fixed-offset only)
            timezone.utc  =  timezone(timedelta(0))
            timezone(timedelta(hours=-5))  =  EST

Key takeaway: Because datetime inherits from date, you can pass a datetime wherever a date is expected. However, time and timedelta are independent classes. They do not share an inheritance relationship with date or datetime.

Frequently Asked Questions

What is the difference between a naive and aware datetime in Python?

A naive datetime has no timezone information attached. Its tzinfo attribute is None. An aware datetime carries a tzinfo object that specifies its UTC offset and timezone name. You cannot directly compare or subtract a naive datetime and an aware datetime; doing so raises a TypeError. Best practice is to always work with aware datetimes (usually in UTC) and only convert to local time for display.

Why is Python's int type arbitrary precision but float is not?

Python's int type uses variable-length internal storage (an array of 30-bit "digits" in CPython), so it can grow as large as available memory allows. The float type, however, is a thin wrapper around C's double, a fixed-size 64-bit IEEE 754 value with a 52-bit mantissa. This gives float about 15-17 significant decimal digits of precision. If you need exact decimal arithmetic (for example, financial calculations), use the decimal.Decimal class instead.

What happens at the Year 2038 problem for Unix timestamps?

Unix timestamps traditionally use a 32-bit signed integer counting seconds since January 1, 1970 UTC. A signed 32-bit integer overflows on January 19, 2038 at 03:14:07 UTC, wrapping to a large negative number. Python itself is unaffected because it uses arbitrary-precision integers for time values. However, C libraries, databases, embedded systems, and file formats that store timestamps in 32-bit fields are vulnerable. Most modern 64-bit operating systems have already migrated to 64-bit time_t.

Why should I use zoneinfo instead of pytz?

The zoneinfo module was added to the Python standard library in Python 3.9 and is the recommended way to handle timezones. Unlike pytz, zoneinfo uses the operating system's IANA timezone database, so no separate pip install is needed. More importantly, zoneinfo correctly handles DST transitions using the fold attribute (PEP 495), while pytz requires you to call normalize() after every arithmetic operation, which is a common source of bugs. If you're on Python 3.9+, always prefer zoneinfo over pytz.

What is banker's rounding and why does Python use it?

Banker's rounding (also called round-half-to-even) rounds values that fall exactly on the 0.5 boundary toward the nearest even number. For example, round(0.5) returns 0, round(1.5) returns 2, round(2.5) returns 2, and round(3.5) returns 4. Python uses this strategy (specified in IEEE 754) because it eliminates the upward bias inherent in "always round 0.5 up." Over many rounding operations, such as financial transactions, this produces more statistically accurate totals.

Related Tools

Python Imports Reference

Import system & module resolution

Datetime Class Hierarchy

object ├── date │ │ .year .month .day │ │ .today() .fromtimestamp() .fromisoformat() │ │ .weekday() .isoformat() .strftime() │ │ │ └── datetime (inherits from date) │ │ .hour .minute .second .microsecond .tzinfo │ │ .now() .utcnow() .combine() .fromisoformat() │ │ .timestamp() .astimezone() .replace() │ │ │ │ ┌──────────────────────────────────┐ │ │ │ Naive: dt.tzinfo is None │ │ │ │ Aware: dt.tzinfo is not None │ │ │ │ dt.utcoffset() != None │ │ │ └──────────────────────────────────┘ │ │ │ └── (no further subclasses in stdlib) │ ├── time │ .hour .minute .second .microsecond .tzinfo │ .fromisoformat() .isoformat() .strftime() │ (represents a time-of-day, independent of any date) │ ├── timedelta │ .days .seconds .microseconds │ .total_seconds() │ (represents a duration, the result of date/datetime subtraction) │ Max: 999999999 days, 23:59:59.999999 │ Min: -999999999 days │ └── tzinfo (abstract base class) │ .utcoffset(dt) .tzname(dt) .dst(dt) │ └── timezone (concrete, fixed-offset only) timezone.utc = timezone(timedelta(0)) timezone(timedelta(hours=-5)) = EST

Frequently Asked Questions

What is the difference between a naive and aware datetime in Python?

Why is Python's int type arbitrary precision but float is not?

What happens at the Year 2038 problem for Unix timestamps?

Why should I use zoneinfo instead of pytz?

What is banker's rounding and why does Python use it?