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')
Raw data
{
"_id": null,
"home_page": "https://github.com/pganssle/pytz-deprecation-shim",
"name": "pytz-deprecation-shim",
"maintainer": "",
"docs_url": null,
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7",
"maintainer_email": "",
"keywords": "",
"author": "Paul Ganssle",
"author_email": "paul@ganssle.io",
"download_url": "https://files.pythonhosted.org/packages/94/f0/909f94fea74759654390a3e1a9e4e185b6cd9aa810e533e3586f39da3097/pytz_deprecation_shim-0.1.0.post0.tar.gz",
"platform": "",
"description": "pytz_deprecation_shim: Shims to help you safely remove pytz\n===========================================================\n\n``pytz`` has served the Python community well for many years, but it is no\nlonger the best option for providing time zones. ``pytz`` has a non-standard\ninterface that is `very easy to misuse\n<https://blog.ganssle.io/articles/2018/03/pytz-fastest-footgun.html>`_; this\ninterface was necessary when ``pytz`` was created, because ``datetime`` had no\nway to represent ambiguous datetimes, but this was solved in in Python 3.6,\nwhich added a ``fold`` attribute to datetimes in `PEP 495\n<https://www.python.org/dev/peps/pep-0495/>`_. With the addition of the\n``zoneinfo`` module in Python 3.9 (`PEP 615\n<https://www.python.org/dev/peps/pep-0615/>`_), there has never been a better\ntime to migrate away from ``pytz``.\n\nHowever, since ``pytz`` time zones are used very differently from a standard\n``tzinfo``, and many libraries have built ``pytz`` zones into their standard\ntime zone interface (and thus may have users relying on the existence of the\n``localize`` and ``normalize`` methods); this library provides shim classes\nthat are compatible with both PEP 495 and ``pytz``'s interface, to make it\neasier for libraries to deprecate ``pytz``.\n\nUsage\n=====\n\nThis library is intended for *temporary usage only*, and should allow you to\ndrop your dependency on ``pytz`` while also giving your users notice that\neventually you will remove support for the ``pytz``-specific interface.\n\nWithin your own code, use ``pytz_deprecation_shim.timezone`` shims as if they\nwere ``zoneinfo`` or ``dateutil.tz`` zones \u2014 do not use ``localize`` or\n``normalize``:\n\n.. code-block:: pycon\n\n >>> import pytz_deprecation_shim as pds\n >>> from datetime import datetime, timedelta\n >>> LA = pds.timezone(\"America/Los_Angeles\")\n\n >>> dt = datetime(2020, 10, 31, 12, tzinfo=LA)\n >>> print(dt)\n 2020-10-31 12:00:00-07:00\n\n >>> dt.tzname()\n 'PDT'\n\n\nDatetime addition will work `like normal Python datetime arithmetic\n<https://blog.ganssle.io/articles/2018/02/aware-datetime-arithmetic.html>`_,\neven across a daylight saving time transition:\n\n.. code-block:: pycon\n\n >>> dt_add = dt + timedelta(days=1)\n\n >>> print(dt_add)\n 2020-11-01 12:00:00-08:00\n\n >>> dt_add.tzname()\n 'PST'\n\nHowever, if you have exposed a time zone to end users who are using ``localize``\nand/or ``normalize`` or any other ``pytz``-specific features (or if you've\nfailed to convert some of your own code all the way), those users will see\na warning (rather than an exception) when they use those features:\n\n.. code-block:: pycon\n\n >>> dt = LA.localize(datetime(2020, 10, 31, 12))\n <stdin>:1: PytzUsageWarning: The localize method is no longer necessary, as\n this time zone supports the fold attribute (PEP 495). For more details on\n migrating to a PEP 495-compliant implementation, see\n https://pytz-deprecation-shim.readthedocs.io/en/latest/migration.html\n\n >>> print(dt)\n 2020-10-31 12:00:00-07:00\n >>> dt.tzname()\n 'PDT'\n\n >>> dt_add = LA.normalize(dt + timedelta(days=1))\n <stdin>:1: PytzUsageWarning: The normalize method is no longer necessary,\n as this time zone supports the fold attribute (PEP 495). For more details\n on migrating to a PEP 495-compliant implementation, see\n https://pytz-deprecation-shim.readthedocs.io/en/latest/migration.html\n\n >>> print(dt_add)\n 2020-11-01 12:00:00-08:00\n >>> dt_add.tzname()\n 'PST'\n\nFor IANA time zones, calling ``str()`` on the shim zones (and indeed on ``pytz``\nand ``zoneinfo`` zones as well) returns the IANA key, so end users who would\nlike to actively migrate to a ``zoneinfo`` (or ``backports.zoneinfo``) can do\nso:\n\n.. code-block:: pycon\n\n >>> from zoneinfo import ZoneInfo\n >>> LA = pds.timezone(\"America/Los_Angeles\")\n >>> LA_zi = ZoneInfo(str(LA))\n >>> print(LA_zi)\n zoneinfo.ZoneInfo(key='America/Los_Angeles')\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Shims to make deprecation of pytz easier",
"version": "0.1.0.post0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "d311c7fac8e259fb03f41911d50e134e",
"sha256": "8314c9692a636c8eb3bda879b9f119e350e93223ae83e70e80c31675a0fdc1a6"
},
"downloads": -1,
"filename": "pytz_deprecation_shim-0.1.0.post0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "d311c7fac8e259fb03f41911d50e134e",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7",
"size": 15734,
"upload_time": "2020-06-17T16:16:28",
"upload_time_iso_8601": "2020-06-17T16:16:28.849774Z",
"url": "https://files.pythonhosted.org/packages/eb/73/3eaab547ca809754e67e06871cff0fc962bafd4b604e15f31896a0f94431/pytz_deprecation_shim-0.1.0.post0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "f563b4bdc56f40acb2498fd1caf6dd1b",
"sha256": "af097bae1b616dde5c5744441e2ddc69e74dfdcb0c263129610d85b87445a59d"
},
"downloads": -1,
"filename": "pytz_deprecation_shim-0.1.0.post0.tar.gz",
"has_sig": false,
"md5_digest": "f563b4bdc56f40acb2498fd1caf6dd1b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7",
"size": 60190,
"upload_time": "2020-06-17T16:16:30",
"upload_time_iso_8601": "2020-06-17T16:16:30.062782Z",
"url": "https://files.pythonhosted.org/packages/94/f0/909f94fea74759654390a3e1a9e4e185b6cd9aa810e533e3586f39da3097/pytz_deprecation_shim-0.1.0.post0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-06-17 16:16:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "pganssle",
"github_project": "pytz-deprecation-shim",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pytz-deprecation-shim"
}
JSON
