Metadata-Version: 2.1
Name: pytz_deprecation_shim
Version: 0.1.0.post0
Summary: Shims to make deprecation of pytz easier
Home-page: https://github.com/pganssle/pytz-deprecation-shim
Author: Paul Ganssle
Author-email: paul@ganssle.io
License: Apache-2.0
Project-URL: Source, https://github.com/pganssle/pytz-deprecation-shim
Project-URL: Bug Reports, https://github.com/pganssle/pytz-deprecation-shim/issues
Project-URL: Documentation, https://pytz-deprecation-shim.readthedocs.io
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: !=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: licenses/LICENSE_APACHE
Requires-Dist: python-dateutil ; python_version < "3.6"
Requires-Dist: tzdata ; python_version >= "3.6"
Requires-Dist: backports.zoneinfo ; python_version >= "3.6" and python_version < "3.9"

pytz_deprecation_shim: Shims to help you safely remove pytz
===========================================================

``pytz`` has served the Python community well for many years, but it is no
longer the best option for providing time zones. ``pytz`` has a non-standard
interface that is `very easy to misuse
<https://blog.ganssle.io/articles/2018/03/pytz-fastest-footgun.html>`_; this
interface was necessary when ``pytz`` was created, because ``datetime`` had no
way to represent ambiguous datetimes, but this was solved in in Python 3.6,
which added a ``fold`` attribute to datetimes in `PEP 495
<https://www.python.org/dev/peps/pep-0495/>`_. With the addition of the
``zoneinfo`` module in Python 3.9 (`PEP 615
<https://www.python.org/dev/peps/pep-0615/>`_), there has never been a better
time to migrate away from ``pytz``.

However, since ``pytz`` time zones are used very differently from a standard
``tzinfo``, and many libraries have built ``pytz`` zones into their standard
time zone interface (and thus may have users relying on the existence of the
``localize`` and ``normalize`` methods); this library provides shim classes
that are compatible with both PEP 495 and ``pytz``'s interface, to make it
easier for libraries to deprecate ``pytz``.

Usage
=====

This library is intended for *temporary usage only*, and should allow you to
drop your dependency on ``pytz`` while also giving your users notice that
eventually you will remove support for the ``pytz``-specific interface.

Within your own code, use ``pytz_deprecation_shim.timezone`` shims as if they
were ``zoneinfo`` or ``dateutil.tz`` zones — do not use ``localize`` or
``normalize``:

.. code-block:: pycon

    >>> import pytz_deprecation_shim as pds
    >>> from datetime import datetime, timedelta
    >>> LA = pds.timezone("America/Los_Angeles")

    >>> dt = datetime(2020, 10, 31, 12, tzinfo=LA)
    >>> print(dt)
    2020-10-31 12:00:00-07:00

    >>> dt.tzname()
    'PDT'


Datetime addition will work `like normal Python datetime arithmetic
<https://blog.ganssle.io/articles/2018/02/aware-datetime-arithmetic.html>`_,
even across a daylight saving time transition:

.. code-block:: pycon

    >>> dt_add = dt + timedelta(days=1)

    >>> print(dt_add)
    2020-11-01 12:00:00-08:00

    >>> dt_add.tzname()
    'PST'

However, if you have exposed a time zone to end users who are using ``localize``
and/or ``normalize`` or any other ``pytz``-specific features (or if you've
failed to convert some of your own code all the way), those users will see
a warning (rather than an exception) when they use those features:

.. code-block:: pycon

    >>> dt = LA.localize(datetime(2020, 10, 31, 12))
    <stdin>:1: PytzUsageWarning: 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
    https://pytz-deprecation-shim.readthedocs.io/en/latest/migration.html

     >>> print(dt)
    2020-10-31 12:00:00-07:00
    >>> dt.tzname()
    'PDT'

    >>> dt_add = LA.normalize(dt + timedelta(days=1))
    <stdin>:1: PytzUsageWarning: 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
    https://pytz-deprecation-shim.readthedocs.io/en/latest/migration.html

    >>> print(dt_add)
    2020-11-01 12:00:00-08:00
    >>> dt_add.tzname()
    'PST'

For IANA time zones, calling ``str()`` on the shim zones (and indeed on ``pytz``
and ``zoneinfo`` zones as well) returns the IANA key, so end users who would
like to actively migrate to a ``zoneinfo`` (or ``backports.zoneinfo``) can do
so:

.. code-block:: pycon

    >>> from zoneinfo import ZoneInfo
    >>> LA = pds.timezone("America/Los_Angeles")
    >>> LA_zi = ZoneInfo(str(LA))
    >>> print(LA_zi)
    zoneinfo.ZoneInfo(key='America/Los_Angeles')