PEP 495: 'Treminology' section and minor edits.

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
+New subclasses must override the base-class ``fromutc()`` method and
-and implement it so that in all cases where two UTC times ``u1``
+implement it so that in all cases where two UTC times ``u1`` and
-and ``u2`` (``u1`` <``u2``) correspond to the same local time
+``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 |
 +-----------------+----------------+-----------------------------+