PEP 495: Applied a patch from Carl Meyer.

pep-0495.txt

@@ -14,7 +14,7 @@ Created: 02-Aug-2015
 Abstract
 ========
 
-This PEP adds a new attribute ``fold`` to the instances of
+This PEP adds a new attribute ``fold`` to instances of the
 ``datetime.time`` and ``datetime.datetime`` classes that can be used
 to differentiate between two moments in time for which local times are
 the same.  The allowed values for the `fold` attribute will be 0 and 1
@@ -25,7 +25,7 @@ possible readings of an ambiguous local time.
 Rationale
 =========
 
-In the most world locations there have been and will be times when
+In most world locations, there have been and will be times when
 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
@@ -75,11 +75,11 @@ Proposal
 The "fold" attribute
 --------------------
 
-We propose adding an attribute called ``fold`` to the instances
-of ``datetime.time`` and ``datetime.datetime`` classes.  This attribute
-should have the value 0 for all instances except those that
-represent the second (chronologically) moment in time in an ambiguous
-case. For those instances, the value will be 1. [#]_
+We propose adding an attribute called ``fold`` to instances of the
+``datetime.time`` and ``datetime.datetime`` classes.  This attribute
+should have the value 0 for all instances except those that represent
+the second (chronologically) moment in time in an ambiguous case. For
+those instances, the value will be 1. [#]_
 
 .. [#] An instance that has ``fold=1`` in a non-ambiguous case is
   said to represent an invalid time (or is invalid for short), but
@@ -116,15 +116,18 @@ Methods
 
 The ``replace()`` methods of the ``datetime.time`` and
 ``datetime.datetime`` classes will get a new keyword-only argument
-called ``fold``.  It will
-behave similarly to the other ``replace()`` arguments: if the ``fold``
-argument is specified and given a value 0 or 1, the new instance
-returned by ``replace()`` will have its ``fold`` attribute set
-to that value.  In CPython, any non-integer value of ``fold`` will
-raise a ``TypeError``, but other implementations may allow the value
-``None`` to behave the same as when ``fold`` is not given.  If the
-``fold`` argument is not specified, the original value of the ``fold``
-attribute is copied to the result.   
+called ``fold``.  It will behave similarly to the other ``replace()``
+arguments: if the ``fold`` argument is specified and given a value 0
+or 1, the new instance returned by ``replace()`` will have its
+``fold`` attribute set to that value.  In CPython, any non-integer
+value of ``fold`` will raise a ``TypeError``, but other
+implementations may allow the value ``None`` to behave the same as
+when ``fold`` is not given. [#]_ If the ``fold`` argument is not
+specified, the original value of the ``fold`` attribute is copied to
+the result.
+
+.. [#] PyPy already allows ``None`` to mean "no change to existing
+       attribute" for all other attributes in ``replace()``.
 
 C-API
 .....
@@ -132,14 +135,14 @@ C-API
 Access macros will be defined to extract the value of ``fold`` from
 ``PyDateTime_DateTime`` and ``PyDateTime_Time`` objects.
 
-.. code:: 
+.. code::
 
   int PyDateTime_GET_FOLD(PyDateTime_DateTime *o)
 
 Return the value of ``fold`` as a C ``int``.
 
-.. code:: 
-  
+.. code::
+
   int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)
 
 Return the value of ``fold`` as a C ``int``.
@@ -150,14 +153,17 @@ instance:
 
 .. code::
 
-  PyObject* PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)
+  PyObject* PyDateTime_FromDateAndTimeAndFold(
+      int year, int month, int day, int hour, int minute,
+      int second, int usecond, int fold)
 
 Return a ``datetime.datetime`` object with the specified year, month,
 day, hour, minute, second, microsecond and fold.
 
 .. code::
 
-  PyObject* PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)
+  PyObject* PyTime_FromTimeAndFold(
+      int hour, int minute, int second, int usecond, int fold)
 
 Return a ``datetime.time`` object with the specified hour, minute,
 second, microsecond and fold.
@@ -267,9 +273,9 @@ instances that differ only by the value of the ``fold`` attribute will
 not be distinguishable by any means other than an explicit access to
 the ``fold`` value.
 
-On the other hand, if object's ``tzinfo`` is set to a fold-aware
+On the other hand, if an object's ``tzinfo`` is set to a fold-aware
 implementation, then the value of ``fold`` will affect the result of
-several methods but only if the corresponding time is in a fold or in
+several methods, but only if the corresponding time is in a fold or in
 a gap: ``utcoffset()``, ``dst()``, ``tzname()``, ``astimezone()``,
 ``strftime()`` (if "%Z" or "%z" directive is used in the format
 specification), ``isoformat()``, and ``timetuple()``.
@@ -311,12 +317,12 @@ No new implementations of ``datetime.tzinfo`` abstract class are
 proposed in this PEP.  The existing (fixed offset) timezones do
 not introduce ambiguous local times and their ``utcoffset()``
 implementation will return the same constant value as they do now
-regardless of the value of ``fold``. 
+regardless of the value of ``fold``.
 
 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
+``datetime.tzinfo`` class will not change.  It is currently not used
+anywhere in the stdlib because the only included ``tzinfo``
+implementation (the ``datetime.timezone`` class implementing fixed
 offset timezones) override ``fromutc()``.
 				   
 
@@ -590,7 +596,7 @@ A non-technical answer
   between fold=0 and fold=1 when I set it for tomorrow 01:30 AM.
   What should I do?
 * Alice: I've never hear of a Py-O-Clock, but I guess fold=0 is
-  the first 01:30 AM and fold=1 is the second. 
+  the first 01:30 AM and fold=1 is the second.
 
 
 A technical reason
@@ -661,7 +667,7 @@ The following alternative names have also been considered:
 
   **repeated**
       Did not receive any support on the mailing list.
- 
+
   **ltdf**
       (Local Time Disambiguation Flag) - short and no-one will attempt
       to guess what it means without reading the docs.  (Feel free to
@@ -761,13 +767,13 @@ hemisphere (where DST is in effect in June) one can get
 
 Note that 12:00 was interpreted as 13:00 by ``mktime``.  With the
 ``datetime.timestamp``, ``datetime.fromtimestamp``, it is currently
-guaranteed that 
+guaranteed that
 
 .. code::
 
   >>> t = datetime.datetime(2015, 6, 1, 12).timestamp()
   >>> datetime.datetime.fromtimestamp(t)
-  datetime.datetime(2015, 6, 1, 12, 0) 
+  datetime.datetime(2015, 6, 1, 12, 0)
 
 This PEP extends the same guarantee to both values of ``fold``:
 
@@ -775,13 +781,13 @@ This PEP extends the same guarantee to both values of ``fold``:
 
   >>> t = datetime.datetime(2015, 6, 1, 12, fold=0).timestamp()
   >>> datetime.datetime.fromtimestamp(t)
-  datetime.datetime(2015, 6, 1, 12, 0) 
+  datetime.datetime(2015, 6, 1, 12, 0)
 
 .. code::
 
   >>> t = datetime.datetime(2015, 6, 1, 12, fold=1).timestamp()
   >>> datetime.datetime.fromtimestamp(t)
-  datetime.datetime(2015, 6, 1, 12, 0) 
+  datetime.datetime(2015, 6, 1, 12, 0)
 
 Thus one of the suggested uses for ``fold=-1`` -- to match the legacy
 behavior -- is not needed.  Either choice of ``fold`` will match the