Implement zoneinfo support and make pytz optional (#940)

3 files changed, 25 insertions, 21 deletions

diff --git a/docs/dates.rst b/docs/dates.rst
index 4420187..8b35091 100644
--- a/docs/dates.rst
+++ b/docs/dates.rst
@@ -276,11 +276,9 @@ class, which you need appropriate implementations for to actually use in your
 application. Babel includes a ``tzinfo`` implementation for UTC (Universal
 Time).
 
-Babel uses `pytz`_ for real timezone support which includes the
-definitions of practically all of the time-zones used on the world, as
-well as important functions for reliably converting from UTC to local
-time, and vice versa.  The module is generally wrapped for you so you can
-directly interface with it from within Babel:
+Babel uses either `zoneinfo`_ or `pytz`_ for timezone support.
+If pytz is installed, it is preferred over the standard library's zoneinfo.
+You can directly interface with either of these modules from within Babel:
 
 .. code-block:: pycon
 
@@ -294,9 +292,9 @@ directly interface with it from within Babel:
 The recommended approach to deal with different time-zones in a Python
 application is to always use UTC internally, and only convert from/to the users
 time-zone when accepting user input and displaying date/time data, respectively.
-You can use Babel together with ``pytz`` to apply a time-zone to any
-``datetime`` or ``time`` object for display, leaving the original information
-unchanged:
+You can use Babel together with ``zoneinfo`` or ``pytz`` to apply a time-zone
+to any ``datetime`` or ``time`` object for display, leaving the original
+information unchanged:
 
 .. code-block:: pycon
 
@@ -314,6 +312,9 @@ For many timezones it's also possible to ask for the next timezone
 transition.  This for instance is useful to answer the question “when do I
 have to move the clock forward next”:
 
+.. warning:: ``get_next_timezone_transition`` is deprecated and will be removed
+             in the next version of Babel
+
 .. code-block:: pycon
 
     >>> t = get_next_timezone_transition('Europe/Vienna', datetime(2011, 3, 2))
@@ -339,7 +340,7 @@ your operating system.  It's provided through the ``LOCALTZ`` constant:
     >>> get_timezone_name(LOCALTZ)
     u'Central European Time'
 
-.. _pytz: http://pytz.sourceforge.net/
+.. _pytz: https://pythonhosted.org/pytz/
 
 
 Localized Time-zone Names
@@ -370,8 +371,9 @@ display a list of time-zones to the user.
 .. code-block:: pycon
 
     >>> from datetime import datetime
+    >>> from babel.dates import _localize
 
-    >>> dt = tz.localize(datetime(2007, 8, 15))
+    >>> dt = _localize(tz, datetime(2007, 8, 15))
     >>> get_timezone_name(dt, locale=Locale.parse('de_DE'))
     u'Mitteleurop\xe4ische Sommerzeit'
     >>> get_timezone_name(tz, locale=Locale.parse('de_DE'))
diff --git a/docs/dev.rst b/docs/dev.rst
index 1c4453d..97a105b 100644
--- a/docs/dev.rst
+++ b/docs/dev.rst
@@ -46,10 +46,9 @@ Unicode is a big deal in Babel.  Here is how the rules are set up:
 Dates and Timezones
 -------------------
 
-Generally all timezone support in Babel is based on pytz which it just
-depends on.  Babel should assume that timezone objects are pytz based
-because those are the only ones with an API that actually work correctly
-(due to the API problems with non UTC based timezones).
+Babel's timezone support relies on either ``pytz`` or ``zoneinfo``; if ``pytz``
+is installed, it is preferred over ``zoneinfo``.  Babel should assume that any
+timezone objects can be from either of these modules.
 
 Assumptions to make:
 
diff --git a/docs/installation.rst b/docs/installation.rst
index 26fe23a..8bf614c 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -4,10 +4,14 @@ Installation
 ============
 
 Babel is distributed as a standard Python package fully set up with all
-the dependencies it needs.  It primarily depends on the excellent `pytz`_
-library for timezone handling.  To install it you can use ``pip``.
+the dependencies it needs.  On Python versions where the standard library
+`zoneinfo`_ module is not available, `pytz`_  needs to be installed for
+timezone support. If `pytz`_  is installed, it is preferred over the
+standard library `zoneinfo`_  module where possible.
 
-.. _pytz: http://pytz.sourceforge.net/
+.. _pytz: https://pythonhosted.org/pytz/
+
+.. _zoneinfo: https://docs.python.org/3/library/zoneinfo.html
 
 .. _virtualenv:
 
@@ -79,16 +83,15 @@ Get the git checkout in a new virtualenv and run in development mode::
     New python executable in venv/bin/python
     Installing distribute............done.
     $ . venv/bin/activate
-    $ pip install pytz
     $ python setup.py import_cldr
     $ pip install --editable .
     ...
     Finished processing dependencies for Babel
 
-Make sure to not forget about the ``pip install pytz`` and ``import_cldr`` steps
-because otherwise you will be missing the locale data.
+Make sure to not forget about the ``import_cldr`` step because otherwise
+you will be missing the locale data.
 The custom setup command will download the most appropriate CLDR release from the
-official website and convert it for Babel but will not work without ``pytz``.
+official website and convert it for Babel.
 
 This will pull also in the dependencies and activate the git head as the
 current version inside the virtualenv.  Then all you have to do is run