diff --git a/pep-0495.txt b/pep-0495.txt index 6ff815e59..ab1b353c5 100644 --- a/pep-0495.txt +++ b/pep-0495.txt @@ -499,7 +499,50 @@ The following alternative names have been proposed: 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 @@ behavior -- is not needed. Either choice of ``first`` will match the 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``