From d5b563e29e9daaefce134b09bf71efae4de0fd70 Mon Sep 17 00:00:00 2001 From: Alexander Belopolsky Date: Sun, 9 Aug 2015 20:33:18 -0400 Subject: [PATCH] PEP 495: 'Treminology' section and minor edits. --- pep-0495.txt | 39 +++++++++++++++++++++++++-------------- 1 file changed, 25 insertions(+), 14 deletions(-) diff --git a/pep-0495.txt b/pep-0495.txt index 0cb0b428c..97ae81ee1 100644 --- a/pep-0495.txt +++ b/pep-0495.txt @@ -37,6 +37,16 @@ particular moment in time. The proposed solution is to add a boolean flag to the ``datetime`` instances that will distinguish between the two ambiguous times. + +Terminology +=========== + +When clocks are moved back, we say that a *fold* is created in the +fabric of time. When the clock are moved forward, a *gap* is created. +A local time that falls in the fold is called *ambiguous*. A local +time that falls in the gap is called *missing*. + + Proposal ======== @@ -118,7 +128,7 @@ Conversion to POSIX seconds from EPOCH The ``timestamp()`` method of ``datetime.datetime`` will return different values for ``datetime.datetime`` instances that differ only by the value of their ``first`` attribute if and only if these instances represent an -ambiguous or a non-existent value. +ambiguous or a non-existent time. When a ``datetime.datetime`` instance ``dt`` represents an ambiguous (repeated) time, there are two values ``s0`` and ``s1`` such that:: @@ -137,7 +147,7 @@ For example, on a system set to US/Eastern timezone:: 1414909800.0 -When a ``datetime.datetime`` instance ``dt`` represents an invalid +When a ``datetime.datetime`` instance ``dt`` represents a missing time, there is no value ``s`` for which:: datetime.fromtimestamp(s) == dt @@ -149,7 +159,7 @@ is always the same as the offset right before the gap and the other is the similar value but in a timezone the UTC offset is always the same as the offset right after the gap. -The value returned by ``dt.timestamp()`` given the invalid +The value returned by ``dt.timestamp()`` given a missing ``dt`` will be the larger of the two "nice to know" values if ``dt.first == True`` and the larger otherwise. @@ -179,10 +189,10 @@ For example, on a system set to US/Eastern timezone:: Combining and splitting date and time ..................................... -The ``datetime.datetime.combine`` method will copy the value of the +The ``datetime.datetime.combine()`` method will copy the value of the ``first`` attribute to the resulting ``datetime.datetime`` instance. -The ``datetime.datetime.time`` method will copy the value of the +The ``datetime.datetime.time()`` method will copy the value of the ``first`` attribute to the resulting ``datetime.time`` instance. @@ -196,7 +206,7 @@ implementation will return the same constant value as they do now regardless of the value of ``first``. The basic implementation of ``fromutc()`` in the abstract -``datetime.tzinfo`` class, will not change. It is currently not +``datetime.tzinfo`` class will not change. It is currently not used anywhere in the stdlib because the only included ``tzinfo`` implementation (the ``datetime.timzeone`` class implementing fixed offset timezones) override ``fromutc()``. @@ -212,15 +222,16 @@ Implementors of concrete ``datetime.tzinfo`` subclasses who want to support variable UTC offsets (due to DST and other causes) must follow these guidelines. -New subclasses must 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 +New subclasses must 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 ``first=True`` and -``fromutc(u2)`` will return an instance with ``first=False``. +``fromutc(u2)`` will return an instance with ``first=False``. In all +other cases the returned instance must have ``first=True``. New implementations of ``utcoffset()`` and ``dst()`` methods should ignore the value of ``first`` unless they are called on the ambiguous -or invalid times. +or missing times. On an ambiguous time introduced at the end of DST, the values returned by ``utcoffset()`` and ``dst()`` methods should be as follows @@ -236,7 +247,7 @@ by ``utcoffset()`` and ``dst()`` methods should be as follows where ``stdoff`` is the standard (non-DST) offset, ``hour = timedelta(hours=1)`` and ``zero = timedelta(0)``. -On an invalid time introduced at the start of DST, the values returned +On a missing time introduced at the start of DST, the values returned by ``utcoffset()`` and ``dst()`` methods should be as follows @@ -249,7 +260,7 @@ by ``utcoffset()`` and ``dst()`` methods should be as follows +-----------------+----------------+------------------+ -On ambiguous/invalid times introduced by the change in the standard time +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 ``first`` and the ``utcoff()`` should return values according to the following table: @@ -259,7 +270,7 @@ according to the following table: +=================+================+=============================+ | ambiguous | oldoff | newoff = oldoff - delta | +-----------------+----------------+-----------------------------+ -| invalid | oldoff | newoff = oldoff + delta | +| missing | oldoff | newoff = oldoff + delta | +-----------------+----------------+-----------------------------+