{"id":2740,"library":"pytz-deprecation-shim","title":"pytz-deprecation-shim","description":"pytz-deprecation-shim provides compatibility shims to ease the migration away from the `pytz` library to PEP 495-compatible time zone implementations like the standard library's `zoneinfo` (Python 3.9+) or `python-dateutil`. It allows existing codebases to gradually deprecate `pytz`-specific interfaces while ensuring continued functionality. The current version is 0.1.0.post0, with the last release in June 2020.","status":"maintenance","version":"0.1.0.post0","language":"en","source_language":"en","source_url":"https://github.com/pganssle/pytz-deprecation-shim","tags":["timezone","pytz","zoneinfo","datetime","migration","shim","deprecation","dateutil"],"install":[{"cmd":"pip install pytz-deprecation-shim","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used internally by the shim for Python 2 compatibility and as a general-purpose timezone provider alongside zoneinfo.","package":"python-dateutil","optional":true},{"reason":"Provides the IANA time zone database used by underlying timezone libraries like zoneinfo and dateutil.","package":"tzdata","optional":false},{"reason":"Provides the 'zoneinfo' module for Python versions older than 3.9, which is wrapped by the shim for Python 3.","package":"backports.zoneinfo","optional":true}],"imports":[{"note":"The shim's `timezone` function is a drop-in replacement for `pytz.timezone` but behaves like a PEP 495-compatible `tzinfo` object.","wrong":"import pytz; pytz.timezone(...)","symbol":"timezone","correct":"from pytz_deprecation_shim import timezone"},{"note":"A shim for `pytz.UTC` that wraps `datetime.timezone.utc` or `dateutil.tz.UTC`.","wrong":"import pytz; pytz.UTC","symbol":"UTC","correct":"from pytz_deprecation_shim import UTC"},{"note":"This warning is raised when `pytz`-specific interfaces (like `localize` or `normalize`) are accessed on shim objects.","symbol":"PytzUsageWarning","correct":"from pytz_deprecation_shim import PytzUsageWarning"}],"quickstart":{"code":"import pytz_deprecation_shim as pds\nfrom datetime import datetime\n\n# Get a timezone using the shim (behaves like zoneinfo/dateutil.tz)\nLA = pds.timezone(\"America/Los_Angeles\")\n\n# Create an aware datetime by directly attaching the tzinfo\ndt = datetime(2020, 10, 31, 12, tzinfo=LA)\nprint(f\"Aware datetime: {dt}\")\nprint(f\"Timezone name: {dt.tzname()}\")\n\n# The shim can also wrap existing PEP 495-compatible time zones\n# from datetime.zoneinfo (Python 3.9+) or dateutil.tz\ntry:\n    from zoneinfo import ZoneInfo\n    NYC_zoneinfo = ZoneInfo(\"America/New_York\")\n    NYC_shim = pds.wrap_zone(NYC_zoneinfo, key=\"America/New_York\")\n    dt_nyc = datetime(2023, 7, 15, 10, tzinfo=NYC_shim)\n    print(f\"Wrapped ZoneInfo datetime: {dt_nyc}\")\nexcept ImportError:\n    print(\"zoneinfo not available (Python < 3.9 or backport not installed)\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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`.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"Usage of `pytz` in any project"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}