1
0
Fork 0
mirror of https://github.com/morpheus65535/bazarr synced 2024-12-23 08:13:14 +00:00
bazarr/libs/pytz_deprecation_shim-0.1.0.post0.dist-info/METADATA

131 lines
5.2 KiB
Text

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')