pytz-deprecation-shim

Warnings

• breaking This library is intended for *temporary* usage during the migration from `pytz`. Your ultimate goal should be to remove this shim and directly use standard library `zoneinfo` (Python 3.9+) or `python-dateutil`.
  Fix: Refactor code to directly use `datetime.datetime.replace(tzinfo=...)` or `datetime(..., tzinfo=...)` instead of `localize()`, and remove calls to `normalize()`. Once all `pytz`-specific interfaces are removed, replace `pytz_deprecation_shim` imports with `zoneinfo` or `dateutil.tz`.
• gotcha Avoid calling `localize()` or `normalize()` methods directly on time zone objects returned by `pytz_deprecation_shim`. While the shim provides these for backward compatibility, their use will raise `PytzUsageWarning` and indicates non-PEP 495 compliant behavior, which should be migrated away from.
  Fix: Instead of `tz.localize(naive_dt)`, use `naive_dt.replace(tzinfo=tz)`. Replace calls to `normalize()` with datetime arithmetic that inherently handles time zone transitions according to PEP 495 semantics.
• gotcha There is a performance overhead associated with using `pytz-deprecation-shim` compared to using the underlying `zoneinfo` or `dateutil.tz` libraries directly, as it involves an additional layer of wrapping.
  Fix: Once the migration from `pytz` is complete and `pytz`-specific interfaces are no longer used, remove `pytz-deprecation-shim` and switch to direct imports of `zoneinfo` or `dateutil.tz` for improved performance.
• gotcha Datetime arithmetic using `pytz_deprecation_shim` objects will follow PEP 495 'wall time' semantics, which differs from `pytz`'s 'add-and-normalize' (absolute time) workflow. This can lead to subtle differences in results, especially across daylight saving time transitions.
  Fix: Carefully review any datetime arithmetic operations during migration. Understand the implications of 'wall time' vs. 'absolute time' arithmetic and adjust logic if necessary. Use `dateutil.tz.enfold` and `datetime.datetime.astimezone` for explicit conversion or handling of ambiguous/non-existent times.
• deprecated The `pytz` library itself is considered deprecated, with `zoneinfo` (Python 3.9+) and `python-dateutil` being the recommended replacements. `pytz-deprecation-shim` exists *because* `pytz` is deprecated.
  Fix: Utilize `pytz-deprecation-shim` as a transitional tool, but plan for full migration to `zoneinfo` or `python-dateutil` as described in its documentation and migration guides.

Install

• pip install pytz-deprecation-shim Install stable version

Imports

• timezone

  from pytz_deprecation_shim import timezone

  The shim's `timezone` function is a drop-in replacement for `pytz.timezone` but behaves like a PEP 495-compatible `tzinfo` object.
• UTC

  from pytz_deprecation_shim import UTC

  A shim for `pytz.UTC` that wraps `datetime.timezone.utc` or `dateutil.tz.UTC`.
• PytzUsageWarning

  from pytz_deprecation_shim import PytzUsageWarning

  This warning is raised when `pytz`-specific interfaces (like `localize` or `normalize`) are accessed on shim objects.

Quickstart

This quickstart demonstrates how to use `pytz_deprecation_shim.timezone` to obtain a time zone object and create an aware datetime by directly assigning the `tzinfo`. It highlights the PEP 495-compatible usage, where `localize()` and `normalize()` are typically avoided. It also shows how to wrap an existing `zoneinfo.ZoneInfo` object.

import pytz_deprecation_shim as pds
from datetime import datetime

# Get a timezone using the shim (behaves like zoneinfo/dateutil.tz)
LA = pds.timezone("America/Los_Angeles")

# Create an aware datetime by directly attaching the tzinfo
dt = datetime(2020, 10, 31, 12, tzinfo=LA)
print(f"Aware datetime: {dt}")
print(f"Timezone name: {dt.tzname()}")

# The shim can also wrap existing PEP 495-compatible time zones
# from datetime.zoneinfo (Python 3.9+) or dateutil.tz
try:
    from zoneinfo import ZoneInfo
    NYC_zoneinfo = ZoneInfo("America/New_York")
    NYC_shim = pds.wrap_zone(NYC_zoneinfo, key="America/New_York")
    dt_nyc = datetime(2023, 7, 15, 10, tzinfo=NYC_shim)
    print(f"Wrapped ZoneInfo datetime: {dt_nyc}")
except ImportError:
    print("zoneinfo not available (Python < 3.9 or backport not installed)")