PEP 495: Rewrote Guidelines for New tzinfo Implementations.
This commit is contained in:
Alexander Belopolsky
parent
a78505b28d
commit
6e5376dde9
134
pep-0495.txt
134
pep-0495.txt
|
|
@ -314,7 +314,7 @@ The basic implementation of ``fromutc()`` in the abstract
|
|||
used anywhere in the stdlib because the only included ``tzinfo``
|
||||
implementation (the ``datetime.timzeone`` class implementing fixed
|
||||
offset timezones) override ``fromutc()``.
|
||||
|
||||
|
||||
|
||||
Guidelines for New tzinfo Implementations
|
||||
=========================================
|
||||
|
|
@ -332,20 +332,102 @@ methods should ignore the value of ``fold`` unless they are called on
|
|||
the ambiguous or missing times.
|
||||
|
||||
|
||||
In the DST Fold
|
||||
---------------
|
||||
In the Fold
|
||||
-----------
|
||||
|
||||
New subclasses should override the base-class ``fromutc()`` method and
|
||||
implement it so that in all cases where two UTC times ``u1`` and
|
||||
``u2`` (``u1`` <``u2``) correspond to the same local time
|
||||
``fromutc(u1)`` will return an instance with ``fold=0`` and
|
||||
``fromutc(u2)`` will return an instance with ``fold=1``. In all
|
||||
implement it so that in all cases where two UTC times ``u0`` and
|
||||
``u1`` (``u0`` <``u1``) correspond to the same local time ``t``,
|
||||
``fromutc(u0)`` will return an instance with ``fold=0`` and
|
||||
``fromutc(u1)`` will return an instance with ``fold=1``. In all
|
||||
other cases the returned instance should have ``fold=0``.
|
||||
|
||||
The ``utcoffset()``, ``tzname()`` and ``dst()`` methods should use the
|
||||
value of the fold attribute to determine whether an otherwise
|
||||
ambiguous time ``t`` corresponds to the time before or after the
|
||||
transition. By definition, ``utcoffset()`` is greater before and
|
||||
smaller after any transition that creates a fold. The values returned
|
||||
by ``tzname()`` and ``dst()`` may or may not depend on the value of
|
||||
the fold attribute depending on the kind of the transition.
|
||||
|
||||
.. image:: pep-0495-fold-2.png
|
||||
:align: center
|
||||
:width: 60%
|
||||
|
||||
The sketch above illustrates the relationship between the UTC and
|
||||
local time around a fall-back transition. The zig-zag line is a graph
|
||||
of the function implemented by ``fromutc()``. Two intervals on the
|
||||
UTC axis adjacent to the transition point and having the size of the
|
||||
time shift at the transition are mapped to the same interval on the
|
||||
local axis. New implementations of ``fromutc()`` method should set
|
||||
the fold attribute to 1 when ``self`` is in the region marked in
|
||||
yellow on the UTC axis. (All intervals should be treated as closed on
|
||||
the left and open on the right.)
|
||||
|
||||
|
||||
Mind the Gap
|
||||
------------
|
||||
|
||||
The ``fromutc()`` method should never produce a time in the gap.
|
||||
|
||||
If ``utcoffset()``, ``tzname()`` or ``dst()`` method is called on a
|
||||
local time that falls in a gap, the rules in effect before the
|
||||
transition should be used if ``fold=0``. Otherwise, the rules in
|
||||
effect after the transition should be used.
|
||||
|
||||
.. image:: pep-0495-gap.png
|
||||
:align: center
|
||||
:width: 60%
|
||||
|
||||
The sketch above illustrates the relationship between the UTC and
|
||||
local time around a spring-forward transition. At the transition, the
|
||||
local clock is advanced skipping the times in the gap. For the
|
||||
purposes of determining the values of ``utcoffset()``, ``tzname()``
|
||||
and ``dst()``, the line before the transition is extended forward to
|
||||
find the UTC time corresponding to the time in the gap with ``fold=0``
|
||||
and for instances with ``fold=1``, the line after the transition is
|
||||
extended back.
|
||||
|
||||
Summary of Rules at a Transition
|
||||
--------------------------------
|
||||
|
||||
On ambiguous/missing times ``utcoffset()`` should return values
|
||||
according to the following table:
|
||||
|
||||
+-----------------+----------------+-----------------------------+
|
||||
| | fold=0 | fold=1 |
|
||||
+=================+================+=============================+
|
||||
| Fold | oldoff | newoff = oldoff - delta |
|
||||
+-----------------+----------------+-----------------------------+
|
||||
| Gap | oldoff | newoff = oldoff + delta |
|
||||
+-----------------+----------------+-----------------------------+
|
||||
|
||||
where ``oldoff`` (``newoff``) is the UTC offset before (after) the
|
||||
transition and ``delta`` is the absolute size of the fold or the gap.
|
||||
|
||||
Note that the interpretation of the fold attribute is consistent in
|
||||
the fold and gap cases. In both cases, ``fold=0`` (``fold=1``) means
|
||||
use ``fromutc()`` line before (after) the transition to find the UTC
|
||||
time. Only in the "Fold" case, the UTC times ``u0`` and ``u1`` are
|
||||
"real" solutions for the equation ``fromutc(u) == t``, while in the
|
||||
"Gap" case they are "imaginary" solutions.
|
||||
|
||||
|
||||
The DST Transitions
|
||||
-------------------
|
||||
|
||||
On a missing time introduced at the start of DST, the values returned
|
||||
by ``utcoffset()`` and ``dst()`` methods should be as follows
|
||||
|
||||
+-----------------+----------------+------------------+
|
||||
| | fold=0 | fold=1 |
|
||||
+=================+================+==================+
|
||||
| utcoffset() | stdoff | stdoff + dstoff |
|
||||
+-----------------+----------------+------------------+
|
||||
| dst() | zero | dstoff |
|
||||
+-----------------+----------------+------------------+
|
||||
|
||||
|
||||
On an ambiguous time introduced at the end of DST, the values returned
|
||||
by ``utcoffset()`` and ``dst()`` methods should be as follows
|
||||
|
||||
|
|
@ -362,44 +444,6 @@ DST correction (typically ``dstoff = timedelta(hours=1)``) and ``zero
|
|||
= timedelta(0)``.
|
||||
|
||||
|
||||
Mind the DST Gap
|
||||
----------------
|
||||
|
||||
.. image:: pep-0495-gap.png
|
||||
:align: center
|
||||
:width: 60%
|
||||
|
||||
On a missing time introduced at the start of DST, the values returned
|
||||
by ``utcoffset()`` and ``dst()`` methods should be as follows
|
||||
|
||||
+-----------------+----------------+------------------+
|
||||
| | fold=0 | fold=1 |
|
||||
+=================+================+==================+
|
||||
| utcoffset() | stdoff | stdoff + dstoff |
|
||||
+-----------------+----------------+------------------+
|
||||
| dst() | zero | dstoff |
|
||||
+-----------------+----------------+------------------+
|
||||
|
||||
|
||||
Non-DST Folds and Gaps
|
||||
----------------------
|
||||
|
||||
On ambiguous/missing times introduced by the change in the standard time
|
||||
offset, the ``dst()`` method should return the same value regardless of
|
||||
the value of ``fold`` and the ``utcoffset()`` should return values
|
||||
according to the following table:
|
||||
|
||||
+-----------------+----------------+-----------------------------+
|
||||
| | fold=0 | fold=1 |
|
||||
+=================+================+=============================+
|
||||
| ambiguous | oldoff | newoff = oldoff - delta |
|
||||
+-----------------+----------------+-----------------------------+
|
||||
| missing | oldoff | newoff = oldoff + delta |
|
||||
+-----------------+----------------+-----------------------------+
|
||||
|
||||
where ``delta`` is the size of the fold or the gap.
|
||||
|
||||
|
||||
Temporal Arithmetic and Comparison Operators
|
||||
============================================
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue