PEP 495: Applied a patch from Carl Meyer.
This commit is contained in:
parent
b528f52152
commit
fe56e39ff6
72
pep-0495.txt
72
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
|
||||
|
|
Loading…
Reference in New Issue