Typing Stubs for pytz

Warnings

• gotcha The `types-pytz` package only provides typing stubs and does NOT install the actual `pytz` runtime library. You must explicitly install `pytz` (e.g., `pip install pytz`) for your code to run, in addition to `types-pytz` for type checking.
  Fix: Ensure both `pytz` and `types-pytz` are installed: `pip install pytz types-pytz`.
• gotcha For Python 3.9 and later, the built-in `zoneinfo` module (part of the standard library) is generally preferred over `pytz` for timezone handling. `zoneinfo` offers better integration with `datetime`, more intuitive API, and avoids some of `pytz`'s historical complexities and potential issues (e.g., the 2038 bug).
  Fix: Consider migrating to `zoneinfo`. For a smoother transition, the `pytz-deprecation-shim` library can help. Example `zoneinfo` usage: `from datetime import datetime; from zoneinfo import ZoneInfo; dt = datetime.now(ZoneInfo('America/New_York'))`.
• gotcha When localizing naive `datetime` objects with `pytz`, it's crucial to use the `.localize()` method of a `pytz` timezone object (e.g., `tz.localize(naive_dt)`). Directly assigning a `pytz` timezone object to a `datetime`'s `tzinfo` attribute (e.g., `naive_dt.replace(tzinfo=tz)`) is often incorrect and can lead to `AmbiguousTimeError`, `NonExistentTimeError`, or subtle shifts to incorrect historical offsets like Local Mean Time (LMT).
  Fix: Always use `pytz.timezone('Continent/City').localize(naive_datetime)` or create timezone-aware datetimes directly with `datetime.now(tz=pytz.utc)` or `datetime(..., tzinfo=pytz.utc)` for UTC. For converting existing aware datetimes, use `.astimezone()`.
• gotcha The `types-pytz` package is developed and released to provide accurate type annotations for specific versions of the `pytz` library. Mismatches between the installed `types-pytz` version and the `pytz` runtime version can lead to incorrect type-checking results (e.g., missing attributes or wrong argument types).
  Fix: Consult the `types-pytz` PyPI page or typeshed `README` for the target `pytz` version it supports. Ensure your `pytz` installation is compatible, upgrading or downgrading if necessary.

Install

• pip install types-pytz Install types-pytz

Imports

• timezone

  from pytz import timezone

• utc

  from pytz import utc

• DstTzInfo

  from pytz.tzinfo import DstTzInfo

  Type stubs define types for the original library; import types directly from `pytz` for type hints, not from `types-pytz`.

Quickstart

This quickstart demonstrates basic usage of `pytz` for creating and converting timezone-aware `datetime` objects. Installing `types-pytz` enables static type checkers to verify the types in such operations, enhancing code reliability.

from datetime import datetime
from pytz import timezone, utc

# Create a naive datetime object
naive_dt = datetime(2024, 7, 21, 10, 30, 0)
print(f"Naive Datetime: {naive_dt}")

# Get a timezone object
eastern = timezone('America/New_York')

# Localize the naive datetime (make it timezone-aware)
aware_dt_eastern = eastern.localize(naive_dt)
print(f"Aware Datetime (Eastern): {aware_dt_eastern}")

# Convert to UTC
aware_dt_utc = aware_dt_eastern.astimezone(utc)
print(f"Aware Datetime (UTC): {aware_dt_utc}")

# Get current time in a specific timezone
current_paris_time = datetime.now(timezone('Europe/Paris'))
print(f"Current Paris Time: {current_paris_time}")

def get_current_utc() -> datetime:
    """Returns the current UTC time with timezone awareness."""
    return datetime.now(utc)

# Demonstrate type checking with a function call
current_utc = get_current_utc()
print(f"Current UTC (from typed function): {current_utc}")