# -*- coding: utf-8 -*-
import warnings
from datetime import tzinfo
from . import _compat
from ._exceptions import (
AmbiguousTimeError,
NonExistentTimeError,
PytzUsageWarning,
UnknownTimeZoneError,
get_exception,
)
IS_DST_SENTINEL = object()
KEY_SENTINEL = object()
def timezone(key, _cache={}):
"""Builds an IANA database time zone shim.
This is the equivalent of ``pytz.timezone``.
:param 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 :exc:`pytz_deprecation_shim.UnknownTimeZoneError` or
``pytz.UnknownTimeZoneError``. Like
:exc:`zoneinfo.ZoneInfoNotFoundError`, both of those are subclasses of
:exc:`KeyError`.
"""
instance = _cache.get(key, None)
if instance is None:
if len(key) == 3 and key.lower() == "utc":
instance = _cache.setdefault(key, UTC)
else:
try:
zone = _compat.get_timezone(key)
except KeyError:
raise get_exception(UnknownTimeZoneError, key)
instance = _cache.setdefault(key, wrap_zone(zone, key=key))
return instance
def fixed_offset_timezone(offset, _cache={}):
"""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.
:param 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.
:return:
A shim time zone.
"""
if not (-1440 < offset < 1440):
raise ValueError("absolute offset is too large", offset)
instance = _cache.get(offset, None)
if instance is None:
if offset == 0:
instance = _cache.setdefault(offset, UTC)
else:
zone = _compat.get_fixed_offset_zone(offset)
instance = _cache.setdefault(offset, wrap_zone(zone, key=None))
return instance
def 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``.
:param zone:
A string to be used as the time zone object's IANA key.
:param fp:
A readable file-like object emitting bytes, pointing to a valid TZif
file.
:return:
A shim time zone.
"""
zone_file = _compat.get_timezone_file(fp)
return wrap_zone(zone_file, key=zone)
def wrap_zone(tz, key=KEY_SENTINEL, _cache={}):
"""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.
:param tz:
A :pep:`495`-compatible time zone, such as those provided by
:mod:`dateutil.tz` or :mod:`zoneinfo`.
:param key:
The value for the IANA time zone key. This is optional for ``zoneinfo``
zones, but required for ``dateutil.tz`` zones.
:return:
A shim time zone.
"""
if key is KEY_SENTINEL:
key = getattr(tz, "key", KEY_SENTINEL)
if key is KEY_SENTINEL:
raise TypeError(
"The `key` argument is required when wrapping zones that do not "
+ "have a `key` attribute."
)
instance = _cache.get((id(tz), key), None)
if instance is None:
instance = _cache.setdefault((id(tz), key), _PytzShimTimezone(tz, key))
return instance
class _PytzShimTimezone(tzinfo):
# Add instance variables for _zone and _key because this will make error
# reporting with partially-initialized _BasePytzShimTimezone objects
# work better.
_zone = None
_key = None
def __init__(self, zone, key):
self._key = key
self._zone = zone
def utcoffset(self, dt):
return self._zone.utcoffset(dt)
def dst(self, dt):
return self._zone.dst(dt)
def tzname(self, dt):
return self._zone.tzname(dt)
def fromutc(self, dt):
# The default fromutc implementation only works if tzinfo is "self"
dt_base = dt.replace(tzinfo=self._zone)
dt_out = self._zone.fromutc(dt_base)
return dt_out.replace(tzinfo=self)
def __str__(self):
if self._key is not None:
return str(self._key)
else:
return repr(self)
def __repr__(self):
return "%s(%s, %s)" % (
self.__class__.__name__,
repr(self._zone),
repr(self._key),
)
def unwrap_shim(self):
"""Returns the underlying class that the shim is a wrapper for.
This is a shim-specific method equivalent to
:func:`pytz_deprecation_shim.helpers.upgrade_tzinfo`. It is provided as
a method to allow end-users to upgrade shim timezones without requiring
an explicit dependency on ``pytz_deprecation_shim``, e.g.:
.. code-block:: python
if getattr(tz, "unwrap_shim", None) is None:
tz = tz.unwrap_shim()
"""
return self._zone
@property
def zone(self):
warnings.warn(
"The zone attribute is specific to pytz's interface; "
+ "please migrate to a new time zone provider. "
+ "For more details on how to do so, see %s"
% PYTZ_MIGRATION_GUIDE_URL,
PytzUsageWarning,
stacklevel=2,
)
return self._key
def localize(self, dt, is_dst=IS_DST_SENTINEL):
warnings.warn(
"The localize method is no longer necessary, as this "
+ "time zone supports the fold attribute (PEP 495). "
+ "For more details on migrating to a PEP 495-compliant "
+ "implementation, see %s" % PYTZ_MIGRATION_GUIDE_URL,
PytzUsageWarning,
stacklevel=2,
)
if dt.tzinfo is not None:
raise ValueError("Not naive datetime (tzinfo is already set)")
dt_out = dt.replace(tzinfo=self)
if is_dst is IS_DST_SENTINEL:
return dt_out
dt_ambiguous = _compat.is_ambiguous(dt_out)
dt_imaginary = (
_compat.is_imaginary(dt_out) if not dt_ambiguous else False
)
if is_dst is None:
if dt_imaginary:
raise get_exception(
NonExistentTimeError, dt.replace(tzinfo=None)
)
if dt_ambiguous:
raise get_exception(AmbiguousTimeError, dt.replace(tzinfo=None))
elif dt_ambiguous or dt_imaginary:
# Start by normalizing the folds; dt_out may have fold=0 or fold=1,
# but we need to know the DST offset on both sides anyway, so we
# will get one datetime representing each side of the fold, then
# decide which one we're going to return.
if _compat.get_fold(dt_out):
dt_enfolded = dt_out
dt_out = _compat.enfold(dt_out, fold=0)
else:
dt_enfolded = _compat.enfold(dt_out, fold=1)
# Now we want to decide whether the fold=0 or fold=1 represents
# what pytz would return for `is_dst=True`
enfolded_dst = bool(dt_enfolded.dst())
if bool(dt_out.dst()) == enfolded_dst:
# If this is not a transition between standard time and
# daylight saving time, pytz will consider the larger offset
# the DST offset.
enfolded_dst = dt_enfolded.utcoffset() > dt_out.utcoffset()
# The default we've established is that dt_out is fold=0; swap it
# for the fold=1 datetime if is_dst == True and the enfolded side
# is DST or if is_dst == False and the enfolded side is *not* DST.
if is_dst == enfolded_dst:
dt_out = dt_enfolded
return dt_out
def normalize(self, dt):
warnings.warn(
"The normalize method is no longer necessary, as this "
+ "time zone supports the fold attribute (PEP 495). "
+ "For more details on migrating to a PEP 495-compliant "
+ "implementation, see %s" % PYTZ_MIGRATION_GUIDE_URL,
PytzUsageWarning,
stacklevel=2,
)
if dt.tzinfo is None:
raise ValueError("Naive time - no tzinfo set")
if dt.tzinfo is self:
return dt
return dt.astimezone(self)
def __copy__(self):
return self
def __deepcopy__(self, memo=None):
return self
def __reduce__(self):
return wrap_zone, (self._zone, self._key)
UTC = wrap_zone(_compat.UTC, "UTC")
PYTZ_MIGRATION_GUIDE_URL = (
"https://pytz-deprecation-shim.readthedocs.io/en/latest/migration.html"
)