[Python-checkins] peps: PEP 495: Are two values enough? // Backward Compatibility

[alexander.belopolsky]

https://hg.python.org/peps/rev/0c65f5c950de
changeset:   5977:0c65f5c950de
user:        Alexander Belopolsky <alexander.belopolsky at gmail.com>
date:        Sat Aug 22 21:22:28 2015 -0400
summary:
  PEP 495: Are two values enough? // Backward Compatibility

files:
  pep-0495.txt |  49 +++++++++++++++++++++++++++++++++++++++-
  1 files changed, 48 insertions(+), 1 deletions(-)


diff --git a/pep-0495.txt b/pep-0495.txt
--- a/pep-0495.txt
+++ b/pep-0495.txt
@@ -499,7 +499,50 @@
 
 
 Are two values enough?
----------------------------------------
+----------------------
+
+Several reasons have been raised to allow a ``None`` or -1 value for
+the ``first`` flag: backward compatibility, analogy with ``tm_isdst``
+and strict checking for invalid times.
+
+
+Backward Compatibility
+......................
+
+This PEP provides only three ways for a program to discover that two
+otherwise identical datetime instances have different values of
+``first``: (1) an explicit check of the ``first`` attribute; (2) if
+the instances are naive - conversion to another timezone using the
+``astimezone()`` method; and (3) conversion to ``float`` using the
+``timestamp()`` method.
+
+Since ``first`` is a new attribute, the first option is not available
+to the existing programs.  Note that option (2) only works for naive
+datetimes that happen to be in a fold or a gap in the system time
+zone.  In all other cases, the value of ``first`` will be ignored in
+the conversion unless the instances use a ``first``-aware ``tzinfo``
+which would not be available in a pre-PEP program.  Similarly, the
+``astimezone()`` called on a naive instance will not be available in
+such program because ``astimezone()`` does not currently work with
+naive datetimes.
+
+This leaves us with only one situation where an existing program can
+start producing diferent results after the implementation of this PEP:
+when a ``datetime.timestamp()`` method is called on a naive datetime
+instance that happen to be in the fold or the gap.  In the current
+implementation, the result is undefined.  Depending on the system
+``mktime`` implementation, the programs can see different results or
+errors in those cases.  With this PEP in place, the value of timestamp
+will be well-defined in those cases but will depend on the value of
+the ``first`` flag.  We consider the change in
+``datetime.timestamp()`` method behavior a bug fix enabled by this
+PEP.  The old behavior can still be emulated by the users who depend
+on it by writing ``time.mktime(dt.timetuple()) + 1e-6*dt.microsecond``
+instead of ``dt.timestamp()``.
+
+
+Analogy with tm_isdst
+.....................
 
 The ``time.mktime`` interface allows three values for the ``tm_isdst``
 flag: -1, 0, and 1.  As we explained above, -1 (asking ``mktime`` to
@@ -564,6 +607,10 @@
 old behavior except in the few cases where the old behavior was
 undefined.
 
+
+Strict Invalid Time Checking
+............................
+
 Another suggestion was to use ``first=-1`` or ``first=None`` to
 indicate that the program truly has no means to deal with the folds
 and gaps and ``dt.utcoffset()`` should raise an error whenever ``dt``

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