Install & Compatibility
Where this runs
tested against v0.1.0.post0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.024s · 20.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.022s · 21MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
timezone
✓ from pytz_deprecation_shim import timezone
✗ import pytz; pytz.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
✗ import pytz; pytz.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.
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)")
Debug
Known issues
breakingThis 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`.fixRefactor 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`.
affects: All versions
gotchaAvoid 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.fixInstead 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.
affects: All versions
gotchaThere 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.fixOnce 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.
affects: All versions
gotchaDatetime 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.fixCarefully 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.
affects: All versions
deprecatedThe `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.fixUtilize `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.
affects: Usage of `pytz` in any project
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pytz_deprecation_shim'
The `pytz-deprecation-shim` package is not installed in the Python environment where the code is being executed.
fixpip install pytz-deprecation-shim
ModuleNotFoundError: No module named 'pytz'
The original `pytz` package is not installed, and `pytz_deprecation_shim.install()` was not called (or called too late) to register the shim as a replacement for `pytz` imports.
fixEnsure `pytz_deprecation_shim.install()` is called very early in your application's lifecycle, *before* any `import pytz` statements. Alternatively, if the shim is not intended, `pip install pytz` to install the original package.
AttributeError: 'ZoneInfo' object has no attribute 'localize'
The `pytz-deprecation-shim` replaces `pytz` timezone objects with standard `zoneinfo` (or `python-dateutil`) `tzinfo` objects, which do not have `pytz`-specific methods like `localize()` or `normalize()`.
fixUse standard `datetime` methods for timezone handling: `naive_dt.replace(tzinfo=tz)` to assign a timezone to a naive datetime, or `aware_dt.astimezone(tz)` to convert an aware datetime to a different timezone.
Upgrade
Version history
0.1.0.post0latest on PyPI · released Jun 17, 2020
Audit
Dependencies
python-dateutiloptionalUsed internally by the shim for Python 2 compatibility and as a general-purpose timezone provider alongside zoneinfo.
tzdatarequiredProvides the IANA time zone database used by underlying timezone libraries like zoneinfo and dateutil.
backports.zoneinfooptionalProvides the 'zoneinfo' module for Python versions older than 3.9, which is wrapped by the shim for Python 3.