[Python-checkins] peps: PEP 495: Rewrote Guidelines for New tzinfo Implementations.

[alexander.belopolsky]

https://hg.python.org/peps/rev/1fa865cbe398
changeset:   6082:1fa865cbe398
user:        Alexander Belopolsky <alexander.belopolsky at gmail.com>
date:        Sun Sep 20 22:42:43 2015 -0400
summary:
  PEP 495: Rewrote Guidelines for New tzinfo Implementations.

files:
  pep-0495.txt |  134 +++++++++++++++++++++++++-------------
  1 files changed, 89 insertions(+), 45 deletions(-)


diff --git a/pep-0495.txt b/pep-0495.txt
--- a/pep-0495.txt
+++ b/pep-0495.txt
@@ -314,7 +314,7 @@
 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 @@
 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 @@
 = 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
 ============================================
 

-- 
Repository URL: https://hg.python.org/peps