API Reference

pytz_deprecation_shim.UTC

The UTC singleton (with an alias at utc) is a shim class wrapping either datetime.timezone.utc or dateutil.tz.UTC.

pytz_deprecation_shim.timezone(key)

Builds an IANA database time zone shim.

This is the equivalent of pytz.timezone.

Parameters

key – A valid key from the IANA time zone database.

Raises

UnknownTimeZoneError – If an unknown value is passed, this will raise an exception that can be caught by pytz_deprecation_shim.UnknownTimeZoneError or pytz.UnknownTimeZoneError. Like zoneinfo.ZoneInfoNotFoundError, both of those are subclasses of KeyError.

pytz_deprecation_shim.fixed_offset_timezone(offset)

Builds a fixed offset time zone shim.

This is the equivalent of pytz.FixedOffset. An alias is available as pytz_deprecation_shim.FixedOffset as well.

Parameters

offset – A fixed offset from UTC, in minutes. This must be in the range -1439 <= offset <= 1439.

Raises

ValueError – For offsets whose absolute value is greater than or equal to 24 hours.

Returns

A shim time zone.

pytz_deprecation_shim.build_tzinfo(zone, fp)

Builds a shim object from a TZif file.

This is a shim for pytz.build_tzinfo. Given a value to use as the zone IANA key and a file-like object containing a valid TZif file (i.e. conforming to RFC 8536), this builds a time zone object and wraps it in a shim class.

The argument names are chosen to match those in pytz.build_tzinfo.

Parameters

  • zone – A string to be used as the time zone object’s IANA key.

  • fp – A readable file-like object emitting bytes, pointing to a valid TZif file.

Returns

A shim time zone.

pytz_deprecation_shim.wrap_zone(tz, key=...)

Wrap an existing time zone object in a shim class.

This is likely to be useful if you would like to work internally with non-pytz zones, but you expose an interface to callers relying on pytz’s interface. It may also be useful for passing non-pytz zones to libraries expecting to use pytz’s interface.

Parameters

  • tz – A PEP 495-compatible time zone, such as those provided by dateutil.tz or zoneinfo.

  • key – The value for the IANA time zone key. This is optional for zoneinfo zones, but required for dateutil.tz zones.

Returns

A shim time zone.

Exceptions

exception pytz_deprecation_shim.PytzUsageWarning

Warning raised when accessing features specific to pytz’s interface.

This warning is used to direct users of pytz-specific features like the localize and normalize methods towards using the standard tzinfo interface, so that these shims can be replaced with one of the underlying libraries they are wrapping.

pytz shim exceptions

These exceptions are intended to mirror at least some of pytz’s exception hierarchy. The shim classes are designed in such a way that the exception classes they raise can be caught either by catching the value in pytz_deprecation_shim or the equivalent exception in pytz (the actual exception type raised will depend on whether or not pytz has been imported, but the value will either be one of the shim exceptions or a subclass of both the shim exception and its pytz equivalent).

exception pytz_deprecation_shim.InvalidTimeError

The base class for exceptions related to folds and gaps.

exception pytz_deprecation_shim.AmbiguousTimeError

Exception raised when is_dst=None for an ambiguous time (fold).

exception pytz_deprecation_shim.NonExistentTimeError

Exception raised when is_dst=None for a non-existent time (gap).

exception pytz_deprecation_shim.UnknownTimeZoneError

Raised when no time zone is found for a specified key.