types-pytz

types-pytz is the PEP 561 stub-only distribution that provides static type annotations for pytz, the widely used Python timezone library. It ships the .pyi stub files maintained in the typeshed project’s stubs/pytz directory, describing the signatures of pytz.timezone(), pytz.utc, the AmbiguousTimeError/NonExistentTimeError exception classes, and the full set of timezone constants pytz exposes at runtime but leaves untyped.

Because pytz itself ships no inline type hints, any codebase using strict mypy or pyright checking against datetime/timezone-aware code needs these stubs installed alongside it to get accurate autocompletion and catch timezone-handling mistakes (like passing a naive datetime where an aware one is expected) at type-check time rather than at runtime.

What You Get

• Complete .pyi type stubs for pytz.timezone(), pytz.utc, pytz.all_timezones, and the full timezone constant set
• Typed signatures for AmbiguousTimeError and NonExistentTimeError, pytz’s DST-transition exception classes
• PEP 561 packaging (a py.typed-equivalent marker) so mypy, pyright, and other conforming type checkers discover the stubs automatically once installed
• Stubs maintained centrally in the typeshed project’s stubs/pytz directory, kept in sync with upstream pytz releases by the typeshed maintainer community
• Version numbers that track the corresponding pytz release plus a stub-revision suffix, so pinning is straightforward alongside the runtime package

Common Use Cases

• Enabling strict mypy or pyright checks in a codebase that localizes or converts datetimes using pytz
• Getting IDE autocompletion and inline signature hints for pytz’s timezone objects and exceptions
• Satisfying CI type-checking gates in projects that pin pytz for legacy timezone handling instead of the standard library’s zoneinfo
• Auditing datetime-handling code for naive-vs-aware timezone mistakes before they surface as runtime bugs

Under The Hood

Architecture - types-pytz contains no executable logic; it is a directory of .pyi stub files under typeshed’s stubs/pytz path that mirror pytz’s public module structure (__init__.pyi, exceptions.pyi, reference.pyi, tzinfo.pyi) so that a type checker resolving import pytz finds matching declarations instead of pytz’s actual (untyped) runtime source.

Tech Stack - Written entirely as PEP 484/561 stub syntax, versioned and published by typeshed’s automated stub_uploader pipeline rather than hand-managed releases; it has no dependencies beyond the type-checker ecosystem that consumes it.

Code Quality - Stubs are reviewed via typeshed’s own PR process (CI validates them against stubtest, which checks stub signatures against pytz’s actual runtime API for drift), so accuracy is enforced automatically rather than by this package’s own test suite — there is no independent test suite specific to stubs/pytz beyond that shared CI gate.

API Design - There is no API to learn: installing types-pytz alongside pytz is transparent to application code, and the only interaction is a type checker silently picking up the stubs — the entire value proposition is zero-friction adoption.