Update from Lennart
This commit is contained in:
Brett Cannon
parent
7057ba616f
commit
039fc5d9da
282
pep-0431.txt
282
pep-0431.txt
|
|
@ -8,7 +8,7 @@ Status: Draft
|
|||
Type: Standards Track
|
||||
Content-Type: text/x-rst
|
||||
Created: 11-Dec-2012
|
||||
Post-History: 11-Dec-2012
|
||||
Post-History: 11-Dec-2012, 28-Dec-2012
|
||||
|
||||
|
||||
Abstract
|
||||
|
|
@ -26,38 +26,41 @@ Concrete time zone support
|
|||
--------------------------
|
||||
|
||||
The time zone support in Python has no concrete implementation in the
|
||||
standard library, only a tzinfo baseclass, and since Python 3.2, one concrete
|
||||
time zone: UTC. To properly support time zones you need to include a database
|
||||
over all time zones, both current and historical, including daylight saving
|
||||
changes. But such information changes frequently, so even if we include the
|
||||
last information in a Python release, that information would be outdated just
|
||||
a few months later.
|
||||
standard library outside of a tzinfo baseclass that supports fixed offsets.
|
||||
To properly support time zones you need to include a database over all time
|
||||
zones, both current and historical, including daylight saving changes.
|
||||
But such information changes frequently, so even if we include the last
|
||||
information in a Python release, that information would be outdated just a
|
||||
few months later.
|
||||
|
||||
Timezone support has therefore only been available through two third-party
|
||||
Time zone support has therefore only been available through two third-party
|
||||
modules, ``pytz`` and ``dateutil``, both who include and wrap the "zoneinfo"
|
||||
database. This database, also called "tz" or "The Olsen database", is the
|
||||
de-facto standard time zone database over time zones, and it is included in
|
||||
most variants of Unix operating systems, including OS X.
|
||||
most Unix and Unix-like operating systems, including OS X.
|
||||
|
||||
This gives us the opportunity to include only the code that supports the
|
||||
zoneinfo data in the standard library, but by default use the operating
|
||||
systems copy of the data, which typically will be kept updated by the
|
||||
updating mechanism of the operating system or distribution.
|
||||
This gives us the opportunity to include the code that supports the zoneinfo
|
||||
data in the standard library, but by default use the operating system's copy
|
||||
of the data, which typically will be kept updated by the updating mechanism
|
||||
of the operating system or distribution.
|
||||
|
||||
For those who have an operating system that does not include the tz database,
|
||||
for example Windows, a distribution containing the latest tz database should
|
||||
also be available at the Python Package Index, so it can be easily installed
|
||||
with the Python packaging tools such as ``easy_install`` or ``pip``. This
|
||||
could also be done on Unices that are no longer receiving updates and
|
||||
therefore have an outdated database.
|
||||
For those who have an operating system that does not include the zoneinfo
|
||||
database, for example Windows, the Python source distribution will include a
|
||||
copy of the zoneinfo database, and a distribution containing the latest
|
||||
zoneinfo database will also be available at the Python Package Index, so it
|
||||
can be easily installed with the Python packaging tools such as
|
||||
``easy_install`` or ``pip``. This could also be done on Unices that are no
|
||||
longer receiving updates and therefore have an outdated database.
|
||||
|
||||
With such a mechanism Python would have full time zone support in the
|
||||
standard library on most platforms, and a simple package installation would
|
||||
provide time zone support on those platforms where the tz database isn't
|
||||
included, such as Windows.
|
||||
standard library on any platform, and a simple package installation would
|
||||
provide an updated time zone database on those platforms where the zoneinfo
|
||||
database isn't included, such as Windows, or on platforms where OS updates
|
||||
are no longer provided.
|
||||
|
||||
The time zone support will be implemented by a new module called ``timezone``,
|
||||
based on Stuart Bishop's ``pytz`` module.
|
||||
The time zone support will be implemented by making the ``datetime`` module
|
||||
into a package, and adding time zone support to ``datetime`` based on Stuart
|
||||
Bishop's ``pytz`` module.
|
||||
|
||||
|
||||
Getting the local time zone
|
||||
|
|
@ -76,16 +79,23 @@ you don't know the name of the time zone. A function in ``datetime`` should
|
|||
be provided to return the local time zone.
|
||||
|
||||
The support for this will be made by integrating Lennart Regebro's
|
||||
``tzlocal`` module into the new ``timezone`` module.
|
||||
``tzlocal`` module into the new ``datetime`` module.
|
||||
|
||||
For Windows it will look up the local Windows time zone name, and use a
|
||||
mapping between Windows time zone names and zoneinfo time zone names provided
|
||||
by the Unicode consortium to convert that to a zoneinfo time zone.
|
||||
|
||||
The mapping should be updated before each major or bugfix release, scripts
|
||||
for doing so will be provided in the ``Tools/`` directory.
|
||||
|
||||
|
||||
Ambiguous times
|
||||
---------------
|
||||
|
||||
When changing over from daylight savings time (DST) the clock is turned back one
|
||||
hour. This means that the times during that hour happens twice, once without
|
||||
DST and then once with DST. Similarly, when changing to daylight savings
|
||||
time, one hour goes missing.
|
||||
When changing over from daylight savings time (DST) the clock is turned back
|
||||
one hour. This means that the times during that hour happens twice, once
|
||||
without DST and then once with DST. Similarly, when changing to daylight
|
||||
savings time, one hour goes missing.
|
||||
|
||||
The current time zone API can not differentiate between the two ambiguous
|
||||
times during a change from DST. For example, in Stockholm the time of
|
||||
|
|
@ -96,10 +106,10 @@ The current time zone API can not disambiguate this and therefore it's
|
|||
unclear which time should be returned::
|
||||
|
||||
# This could be either 00:00 or 01:00 UTC:
|
||||
>>> dt = datetime(2012, 11, 28, 2, 0, tzinfo=timezone('Europe/Stockholm'))
|
||||
>>> dt = datetime(2012, 10, 28, 2, 0, tzinfo=zoneinfo('Europe/Stockholm'))
|
||||
# But we can not specify which:
|
||||
>>> dt.astimezone(timezone('UTC'))
|
||||
datetime.datetime(2012, 11, 28, 1, 0, tzinfo=<UTC>)
|
||||
>>> dt.astimezone(zoneinfo('UTC'))
|
||||
datetime.datetime(2012, 10, 28, 1, 0, tzinfo=<UTC>)
|
||||
|
||||
``pytz`` solved this problem by adding ``is_dst`` parameters to several
|
||||
methods of the tzinfo objects to make it possible to disambiguate times when
|
||||
|
|
@ -108,88 +118,131 @@ this is desired.
|
|||
This PEP proposes to add these ``is_dst`` parameters to the relevant methods
|
||||
of the ``datetime`` API, and therefore add this functionality directly to
|
||||
``datetime``. This is likely the hardest part of this PEP as this involves
|
||||
updating the
|
||||
updating the C version of the ``datetime`` library with this functionality,
|
||||
as this involved writing new code, and not just reorganizing existing
|
||||
external libraries.
|
||||
|
||||
|
||||
Implementation API
|
||||
==================
|
||||
|
||||
The new ``timezone``-module
|
||||
---------------------------
|
||||
The zoneinfo database
|
||||
---------------------
|
||||
|
||||
The public API of the new ``timezone``-module contains one new class, one new
|
||||
function and one new exception.
|
||||
The latest version of the zoneinfo database should exist in the
|
||||
``Lib/tzdata`` directory of the Python source control system. This copy of
|
||||
the database should be updated before every Python feature and bug-fix
|
||||
release, but not for releases of Python versions that are in
|
||||
security-fix-only-mode.
|
||||
|
||||
* New class: ``DstTzInfo``
|
||||
Scripts to update the database will be provided in ``Tools/``, and the
|
||||
release instructions will be updated to include this update.
|
||||
|
||||
This class provides a concrete implementation of the ``zoneinfo`` base
|
||||
class that implements DST support.
|
||||
New configure options ``--enable-internal-timezone-database`` and
|
||||
``--disable-internal-timezone-database`` will be implemented to enable and
|
||||
disable the installation of this database when installing from source. A
|
||||
source install will default to installing them.
|
||||
|
||||
Binary installers for systems that have a system-provided zoneinfo database
|
||||
may skip installing the included database since it would never be used for
|
||||
these platforms. For other platforms, for example Windows, binary installers
|
||||
must install the included database.
|
||||
|
||||
|
||||
* New function :``get_timezone(name=None, db=None)``
|
||||
Changes in the ``datetime``-module
|
||||
----------------------------------
|
||||
|
||||
This function takes a name string that must be a string specifying a
|
||||
valid zoneinfo timezone, i.e. "US/Eastern", "Europe/Warsaw" or "Etc/GMT+11".
|
||||
If not given, the local timezone will be looked up. If an invalid zone name
|
||||
is given, or the local timezone can not be retrieved, the function raises
|
||||
`UnknownTimeZoneError`.
|
||||
The public API of the new time zone support contains one new class, one new
|
||||
function, one new exception and four new collections. In addition to this, several
|
||||
methods on the datetime object gets a new ``is_dst`` parameter.
|
||||
|
||||
The function also takes an optional path to the location of the zoneinfo
|
||||
database which should be used. If not specified, the function will check if
|
||||
the `timezonedata` module is installed, and then use that location or
|
||||
otherwise use the database in ``/usr/share/zoneinfo``.
|
||||
New class ``DstTzInfo``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If no database is found an ``UnknownTimeZoneError`` or subclass thereof will
|
||||
be raised with a message explaining that no zoneinfo database can be found,
|
||||
but that you can install one with the ``timezonedata`` package.
|
||||
This class provides a concrete implementation of the ``zoneinfo`` base
|
||||
class that implements DST support.
|
||||
|
||||
|
||||
* New Exception: ``UnknownTimeZoneError``
|
||||
New function ``zoneinfo(name=None, db_path=None)``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This exception is raised when giving a time zone specification that can't be
|
||||
found::
|
||||
This function takes a name string that must be a string specifying a
|
||||
valid zoneinfo time zone, i.e. "US/Eastern", "Europe/Warsaw" or "Etc/GMT".
|
||||
If not given, the local time zone will be looked up. If an invalid zone name
|
||||
is given, or the local time zone can not be retrieved, the function raises
|
||||
`UnknownTimeZoneError`.
|
||||
|
||||
The function also takes an optional path to the location of the zoneinfo
|
||||
database which should be used. If not specified, the function will look for
|
||||
databases in the following order:
|
||||
|
||||
1. Use the database in ``/usr/share/zoneinfo``, if it exists.
|
||||
|
||||
2. Check if the `tzdata-update` module is installed, and then use that
|
||||
database.
|
||||
|
||||
3. Use the Python-provided database in ``Lib/tzdata``.
|
||||
|
||||
If no database is found an ``UnknownTimeZoneError`` or subclass thereof will
|
||||
be raised with a message explaining that no zoneinfo database can be found,
|
||||
but that you can install one with the ``tzdata-update`` package.
|
||||
|
||||
|
||||
New parameter ``is_dst``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
A new ``is_dst`` parameter is added to several methods to handle time
|
||||
ambiguity during DST changeovers.
|
||||
|
||||
* ``tzinfo.utcoffset(dt, is_dst=False)``
|
||||
|
||||
* ``tzinfo.dst(dt, is_dst=False)``
|
||||
|
||||
* ``tzinfo.tzname(dt, is_dst=False)``
|
||||
|
||||
* ``datetime.astimezone(tz, is_dst=False)``
|
||||
|
||||
The ``is_dst`` parameter can be ``False`` (default), ``True``, or ``None``.
|
||||
|
||||
``False`` will specify that the given datetime should be interpreted as not
|
||||
happening during daylight savings time, i.e. that the time specified is after
|
||||
the change from DST.
|
||||
|
||||
``True`` will specify that the given datetime should be interpreted as happening
|
||||
during daylight savings time, i.e. that the time specified is before the change
|
||||
from DST.
|
||||
|
||||
``None`` will raise an ``AmbiguousTimeError`` exception if the time specified
|
||||
was during a DST change over. It will also raise a ``NonExistentTimeError``
|
||||
if a time is specified during the "missing time" in a change to DST.
|
||||
|
||||
New exceptions
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
* ``UnknownTimeZoneError``
|
||||
|
||||
This exception is a subclass of KeyError and raised when giving a time
|
||||
zone specification that can't be found::
|
||||
|
||||
>>> datetime.Timezone('Europe/New_York')
|
||||
Traceback (most recent call last):
|
||||
...
|
||||
UnknownTimeZoneError: There is no time zone called 'Europe/New_York'
|
||||
|
||||
* ``InvalidTimeError``
|
||||
|
||||
Changes in the ``datetime``-module
|
||||
--------------------------------------
|
||||
|
||||
A new ``is_dst`` parameter is added to several of the `tzinfo` methods to
|
||||
handle time ambiguity during DST changeovers.
|
||||
|
||||
* ``tzinfo.utcoffset(self, dt, is_dst=True)``
|
||||
|
||||
* ``tzinfo.dst(self, dt, is_dst=True)``
|
||||
|
||||
* ``tzinfo.tzname(self, dt, is_dst=True)``
|
||||
|
||||
The ``is_dst`` parameter can be ``True`` (default), ``False``, or ``None``.
|
||||
|
||||
``True`` will specify that the given datetime should be interpreted as
|
||||
happening during daylight savings time, i.e. that the time specified is before
|
||||
the change from DST.
|
||||
|
||||
``False`` will specify that the given datetime should be interpreted as not
|
||||
happening during daylight savings time, i.e. that the time specified is after
|
||||
the change from DST.
|
||||
|
||||
``None`` will raise an ``AmbiguousTimeError`` exception if the time specified
|
||||
was during a DST change over. It will also raise a ``NonExistentTimeError``
|
||||
if a time is specified during the "missing time" in a change to DST.
|
||||
|
||||
There are also two new exceptions:
|
||||
This exception serves as a base for ``AmbiguousTimeError`` and
|
||||
``NonExistentTimeError``, to enable you to trap these two separately. It
|
||||
will subclass from ValueError, so that you can catch these errors together
|
||||
with inputs like the 29th of February 2011.
|
||||
|
||||
* ``AmbiguousTimeError``
|
||||
|
||||
This exception is raised when giving a datetime specification that is
|
||||
ambiguous while setting ``is_dst`` to None::
|
||||
This exception is raised when giving a datetime specification that is ambiguous
|
||||
while setting ``is_dst`` to None::
|
||||
|
||||
>>> datetime(2012, 11, 28, 2, 0, tzinfo=timezone('Europe/Stockholm'), is_dst=None)
|
||||
>>>
|
||||
>>> datetime(2012, 11, 28, 2, 0, tzinfo=zoneinfo('Europe/Stockholm'), is_dst=None)
|
||||
>>>
|
||||
Traceback (most recent call last):
|
||||
...
|
||||
AmbiguousTimeError: 2012-10-28 02:00:00 is ambiguous in time zone Europe/Stockholm
|
||||
|
|
@ -197,17 +250,31 @@ There are also two new exceptions:
|
|||
|
||||
* ``NonExistentTimeError``
|
||||
|
||||
This exception is raised when giving a datetime specification that is
|
||||
non-existent while setting ``is_dst`` to None::
|
||||
This exception is raised when giving a datetime specification that is ambiguous
|
||||
while setting ``is_dst`` to None::
|
||||
|
||||
>>> datetime(2012, 3, 25, 2, 0, tzinfo=timezone('Europe/Stockholm'), is_dst=None)
|
||||
>>>
|
||||
>>> datetime(2012, 3, 25, 2, 0, tzinfo=zoneinfo('Europe/Stockholm'), is_dst=None)
|
||||
>>>
|
||||
Traceback (most recent call last):
|
||||
...
|
||||
NonExistentTimeError: 2012-03-25 02:00:00 does not exist in time zone Europe/Stockholm
|
||||
|
||||
|
||||
The ``timezonedata``-package
|
||||
New collections
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
* ``all_timezones`` is the exhaustive list of the time zone names that can
|
||||
be used, listed alphabethically.
|
||||
|
||||
* ``all_timezones_set`` is a set of the time zones in ``all_timezones``.
|
||||
|
||||
* ``common_timezones`` is a list of useful, current time zones, listed
|
||||
alphabethically.
|
||||
|
||||
* ``common_timezones_set`` is a set of the time zones in ``common_timezones``.
|
||||
|
||||
|
||||
The ``tzdata-update``-package
|
||||
-----------------------------
|
||||
|
||||
The zoneinfo database will be packaged for easy installation with
|
||||
|
|
@ -215,6 +282,10 @@ The zoneinfo database will be packaged for easy installation with
|
|||
Python code, and will not contain any Python code except that which is needed
|
||||
for installation.
|
||||
|
||||
It will be kept updated with the same tools as the internal database, but
|
||||
released whenever the ``zoneinfo``-database is updated, and use the same
|
||||
version schema.
|
||||
|
||||
|
||||
Differences from the ``pytz`` API
|
||||
=================================
|
||||
|
|
@ -223,28 +294,15 @@ Differences from the ``pytz`` API
|
|||
around that ``tzinfo`` doesn't have is_dst. When ``is_dst`` is
|
||||
implemented directly in ``datetime.tzinfo`` they are no longer needed.
|
||||
|
||||
* The ``pytz`` method ``timezone()`` is instead called ``get_timezone()`` for
|
||||
clarity.
|
||||
* The ``timezone()`` function is called ``zoneinfo()`` to avoid clashing with
|
||||
the ``timezone`` class introduced in Python 3.2.
|
||||
|
||||
* ``get_timezone()`` will return the local time zone if called without
|
||||
arguments.
|
||||
* ``zoneinfo()`` will return the local time zone if called without arguments.
|
||||
|
||||
* The class ``pytz.StaticTzInfo`` is there to provide the ``is_dst`` support
|
||||
for static timezones. When ``is_dst`` support is included in
|
||||
``datetime.tzinfo`` it is no longer needed.
|
||||
* The class ``pytz.StaticTzInfo`` is there to provide the ``is_dst`` support for static
|
||||
time zones. When ``is_dst`` support is included in ``datetime.tzinfo`` it is no longer needed.
|
||||
|
||||
|
||||
Discussion
|
||||
==========
|
||||
|
||||
Should the windows installer include the data package?
|
||||
------------------------------------------------------
|
||||
|
||||
It has been suggested that the Windows installer should include the data
|
||||
package. This would mean that an explicit installation would no longer be
|
||||
needed on Windows. On the other hand, that would mean that many using Windows
|
||||
would not be aware that the database quickly becomes outdated and would not
|
||||
keep it updated.
|
||||
* ``InvalidTimeError`` subclasses from ``ValueError``.
|
||||
|
||||
|
||||
Resources
|
||||
|
|
@ -256,6 +314,8 @@ Resources
|
|||
|
||||
* http://pypi.python.org/pypi/python-dateutil
|
||||
|
||||
* http://unicode.org/cldr/data/common/supplemental/windowsZones.xml
|
||||
|
||||
Copyright
|
||||
=========
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue