[Python-checkins] peps: Updated PEP 495:

[alexander.belopolsky]

https://hg.python.org/peps/rev/2b74b0189b83
changeset:   5945:2b74b0189b83
user:        Alexander Belopolsky <alexander.belopolsky at gmail.com>
date:        Sun Aug 09 19:51:45 2015 -0400
summary:
  Updated	PEP 495:

  * Explained creation of invalid instances.
  * Added "Combining and splitting date and time" section.
  * Clarified that fromutc() will not change.
  * Removed a paragraph listing methods that can produce first=False.
  * Corrected spelling mistakes.

files:
  pep-0495.txt |  60 ++++++++++++++++++++++++++++------------
  1 files changed, 42 insertions(+), 18 deletions(-)


diff --git a/pep-0495.txt b/pep-0495.txt
--- a/pep-0495.txt
+++ b/pep-0495.txt
@@ -29,7 +29,7 @@
 =========
 
 In the most world locations there have been and will be times when
-local clocks are moved back.  In those times intervals are introduced
+local clocks are moved back.  In those times, intervals are introduced
 in which local clocks show the same time twice in the same day.  In
 these situations, the information displayed on a local clock (or
 stored in a Python datetime instance) is insufficient to identify a
@@ -47,7 +47,18 @@
 of ``datetime.time`` and ``datetime.datetime`` classes.  This member
 should have the value True for all instances except those that
 represent the second (chronologically) moment in time in an ambiguous
-case.
+case. [#]_
+
+.. [#] An instance that has ``first=False`` in a non-ambiguous case is
+  said to represent an invalid time (or is invalid for short), but
+  users are not prevented from creating invalid instances by passing
+  ``first=False`` to a constructor or to a ``replace()`` method.  This
+  is similar to the current situation with the instances that fall in
+  the spring-forward gap.  Such instances don't represent any valid
+  time, but neither the constructors nor the ``replace()`` methods
+  check whether the instances that they produce are valid.  Moreover,
+  this PEP specifies how various functions should behave when given an
+  invalid instance.
 
 Affected APIs
 -------------
@@ -72,8 +83,8 @@
 
 The ``replace()`` methods of the ``datetime.time`` and
 ``datetime.datetime`` classes will get a new keyword-only argument
-called ``first`` with the default value ``True``.  It will
-becave similarly to the other ``replace()`` arguments: if the ``first``
+called ``first``.  It will
+behave similarly to the other ``replace()`` arguments: if the ``first``
 argument is specified and given a boolean value, the new instance
 returned by ``replace()`` will have its ``first`` attribute set
 to that value.  In CPython, a non-boolean value of ``first`` will
@@ -165,6 +176,16 @@
   datetime.datetime(2014, 11, 2, 1, 30, first=False)
 
 
+Combining and splitting date and time
+.....................................
+
+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
+``first`` attribute to the resulting ``datetime.time`` instance.
+
+
 Implementations of tzinfo in stdlib
 ...................................
 
@@ -174,6 +195,12 @@
 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
+used anywhere in the stdlib because the only included ``tzinfo``
+implementation (the ``datetime.timzeone`` class implementing fixed
+offset timezones) override ``fromutc()``.
+
 New guidelines will be published for implementing concrete timezones
 with variable UTC offset.
 
@@ -185,11 +212,11 @@
 support variable UTC offsets (due to DST and other causes) must follow
 these guidelines.
 
-New subclasses should override the baseclass ``fromutc()`` method so
-that in all cases where two UTC times ``u1`` and ``u2`` (``u1`` <``u2``)
-corespond to the same local time ``fromutc(u1)`` will return an instance
-with ``first=True`` and ``fromutc(u1)`` will return an instance
-with ``first=False``.
+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``.
 
 New implementations of ``utcoffset()`` and ``dst()`` methods should
 ignore the value of ``first`` unless they are called on the ambiguous
@@ -259,20 +286,17 @@
 --------------------
 
 The value of "first" will be ignored in all operations except those
-that involve conversion between timezones. [#]_
+that involve conversion between timezones. [#]_ As a consequence,
+`datetime.datetime`` or ``datetime.time`` instances that differ only
+by the value of ``first`` will compare as equal.  Applications that
+need to differentiate between such instances should check the value of
+``first`` or convert them to a timezone that does not have ambiguous
+times.
 
 The result of addition (subtraction) of a timedelta to (from) a
 datetime will always have ``first`` set to ``True`` even if the
 original datetime instance had ``first=False``.
 
-(The only methods that will be able to produce non-default value of
-"first" are ``__new__``, and ``replace()`` methods of the
-``datetime.datetime`` and ``datetime.time`` classes ``now()``,
-``astimezone()`` and ``fromtimestamp()`` methods of the
-``datetime.datetime`` class, and ``fromutc()`` method of some tzinfo
-implementations.)
-
-
 .. [#] As of Python 3.5, ``tzinfo`` is ignored whenever timedelta is
    added or subtracted from a ``datetime.datetime`` instance or when
    one ``datetime.datetime`` instance is subtracted from another with

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