traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

#13076: merge with 3.2.

This commit is contained in:
Ezio Melotti 2011-10-02 12:47:10 +03:00
parent 267aa24365 35ec7f771b
commit 6fe679f011
1 changed files with 76 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
Doc/library/datetime.rst
View File

@ -18,13 +18,13 @@ functionality, see also the :mod:`time` and :mod:`calendar` modules.
There are two kinds of date and time objects: "naive" and "aware". This
distinction refers to whether the object has any notion of time zone, daylight
saving time, or other kind of algorithmic or political time adjustment. Whether
a naive :class:`datetime` object represents Coordinated Universal Time (UTC),
a naive :class:`.datetime` object represents Coordinated Universal Time (UTC),
local time, or time in some other timezone is purely up to the program, just
like it's up to the program whether a particular number represents metres,
miles, or mass. Naive :class:`datetime` objects are easy to understand and to
miles, or mass. Naive :class:`.datetime` objects are easy to understand and to
work with, at the cost of ignoring some aspects of reality.
For applications requiring more, :class:`datetime` and :class:`time` objects
For applications requiring more, :class:`.datetime` and :class:`.time` objects
have an optional time zone information attribute, :attr:`tzinfo`, that can be
set to an instance of a subclass of the abstract :class:`tzinfo` class. These
:class:`tzinfo` objects capture information about the offset from UTC time, the
@ -41,13 +41,13 @@ The :mod:`datetime` module exports the following constants:
.. data:: MINYEAR
The smallest year number allowed in a :class:`date` or :class:`datetime` object.
The smallest year number allowed in a :class:`date` or :class:`.datetime` object.
:const:`MINYEAR` is ``1``.
.. data:: MAXYEAR
The largest year number allowed in a :class:`date` or :class:`datetime` object.
The largest year number allowed in a :class:`date` or :class:`.datetime` object.
:const:`MAXYEAR` is ``9999``.
@ -91,14 +91,14 @@ Available Types
.. class:: timedelta
:noindex:
A duration expressing the difference between two :class:`date`, :class:`time`,
or :class:`datetime` instances to microsecond resolution.
A duration expressing the difference between two :class:`date`, :class:`.time`,
or :class:`.datetime` instances to microsecond resolution.
.. class:: tzinfo
An abstract base class for time zone information objects. These are used by the
:class:`datetime` and :class:`time` classes to provide a customizable notion of
:class:`.datetime` and :class:`.time` classes to provide a customizable notion of
time adjustment (for example, to account for time zone and/or daylight saving
time).
@ -114,7 +114,7 @@ Objects of these types are immutable.
Objects of the :class:`date` type are always naive.
An object *d* of type :class:`time` or :class:`datetime` may be naive or aware.
An object *d* of type :class:`.time` or :class:`.datetime` may be naive or aware.
*d* is aware if ``d.tzinfo`` is not ``None`` and ``d.tzinfo.utcoffset(d)`` does
not return ``None``. If ``d.tzinfo`` is ``None``, or if ``d.tzinfo`` is not
``None`` but ``d.tzinfo.utcoffset(d)`` returns ``None``, *d* is naive.
@ -299,7 +299,7 @@ Notes:
-1 day, 19:00:00
In addition to the operations listed above :class:`timedelta` objects support
certain additions and subtractions with :class:`date` and :class:`datetime`
certain additions and subtractions with :class:`date` and :class:`.datetime`
objects (see below).
.. versionchanged:: 3.2
@ -638,10 +638,10 @@ Example of working with :class:`date`:
:class:`datetime` Objects
-------------------------
A :class:`datetime` object is a single object containing all the information
from a :class:`date` object and a :class:`time` object. Like a :class:`date`
object, :class:`datetime` assumes the current Gregorian calendar extended in
both directions; like a time object, :class:`datetime` assumes there are exactly
A :class:`.datetime` object is a single object containing all the information
from a :class:`date` object and a :class:`.time` object. Like a :class:`date`
object, :class:`.datetime` assumes the current Gregorian calendar extended in
both directions; like a time object, :class:`.datetime` assumes there are exactly
3600\*24 seconds in every day.
Constructor:
@ -689,7 +689,7 @@ Other constructors, all class methods:
Return the current UTC date and time, with :attr:`tzinfo` ``None``. This is like
:meth:`now`, but returns the current UTC date and time, as a naive
:class:`datetime` object. An aware current UTC datetime can be obtained by
:class:`.datetime` object. An aware current UTC datetime can be obtained by
calling ``datetime.now(timezone.utc)``. See also :meth:`now`.
.. classmethod:: datetime.fromtimestamp(timestamp, tz=None)
@ -697,7 +697,7 @@ Other constructors, all class methods:
Return the local date and time corresponding to the POSIX timestamp, such as is
returned by :func:`time.time`. If optional argument *tz* is ``None`` or not
specified, the timestamp is converted to the platform's local date and time, and
the returned :class:`datetime` object is naive.
the returned :class:`.datetime` object is naive.
Else *tz* must be an instance of a class :class:`tzinfo` subclass, and the
timestamp is converted to *tz*'s time zone. In this case the result is
@ -710,12 +710,12 @@ Other constructors, all class methods:
1970 through 2038. Note that on non-POSIX systems that include leap seconds in
their notion of a timestamp, leap seconds are ignored by :meth:`fromtimestamp`,
and then it's possible to have two timestamps differing by a second that yield
identical :class:`datetime` objects. See also :meth:`utcfromtimestamp`.
identical :class:`.datetime` objects. See also :meth:`utcfromtimestamp`.
.. classmethod:: datetime.utcfromtimestamp(timestamp)
Return the UTC :class:`datetime` corresponding to the POSIX timestamp, with
Return the UTC :class:`.datetime` corresponding to the POSIX timestamp, with
:attr:`tzinfo` ``None``. This may raise :exc:`ValueError`, if the timestamp is
out of the range of values supported by the platform C :c:func:`gmtime` function.
It's common for this to be restricted to years in 1970 through 2038. See also
@ -740,7 +740,7 @@ Other constructors, all class methods:
.. classmethod:: datetime.fromordinal(ordinal)
Return the :class:`datetime` corresponding to the proleptic Gregorian ordinal,
Return the :class:`.datetime` corresponding to the proleptic Gregorian ordinal,
where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1
<= ordinal <= datetime.max.toordinal()``. The hour, minute, second and
microsecond of the result are all 0, and :attr:`tzinfo` is ``None``.
@ -748,18 +748,18 @@ Other constructors, all class methods:
.. classmethod:: datetime.combine(date, time)
Return a new :class:`datetime` object whose date components are equal to the
Return a new :class:`.datetime` object whose date components are equal to the
given :class:`date` object's, and whose time components and :attr:`tzinfo`
attributes are equal to the given :class:`time` object's. For any
:class:`datetime` object *d*,
attributes are equal to the given :class:`.time` object's. For any
:class:`.datetime` object *d*,
``d == datetime.combine(d.date(), d.timetz())``. If date is a
:class:`datetime` object, its time components and :attr:`tzinfo` attributes
:class:`.datetime` object, its time components and :attr:`tzinfo` attributes
are ignored.
.. classmethod:: datetime.strptime(date_string, format)
Return a :class:`datetime` corresponding to *date_string*, parsed according to
Return a :class:`.datetime` corresponding to *date_string*, parsed according to
*format*. This is equivalent to ``datetime(*(time.strptime(date_string,
format)[0:6]))``. :exc:`ValueError` is raised if the date_string and format
can't be parsed by :func:`time.strptime` or if it returns a value which isn't a
@ -771,19 +771,19 @@ Class attributes:
.. attribute:: datetime.min
The earliest representable :class:`datetime`, ``datetime(MINYEAR, 1, 1,
The earliest representable :class:`.datetime`, ``datetime(MINYEAR, 1, 1,
tzinfo=None)``.
.. attribute:: datetime.max
The latest representable :class:`datetime`, ``datetime(MAXYEAR, 12, 31, 23, 59,
The latest representable :class:`.datetime`, ``datetime(MAXYEAR, 12, 31, 23, 59,
59, 999999, tzinfo=None)``.
.. attribute:: datetime.resolution
The smallest possible difference between non-equal :class:`datetime` objects,
The smallest possible difference between non-equal :class:`.datetime` objects,
``timedelta(microseconds=1)``.
@ -826,24 +826,24 @@ Instance attributes (read-only):
.. attribute:: datetime.tzinfo
The object passed as the *tzinfo* argument to the :class:`datetime` constructor,
The object passed as the *tzinfo* argument to the :class:`.datetime` constructor,
or ``None`` if none was passed.
Supported operations:
+---------------------------------------+-------------------------------+
| Operation | Result |
+=======================================+===============================+
| ``datetime2 = datetime1 + timedelta`` | \(1) |
+---------------------------------------+-------------------------------+
| ``datetime2 = datetime1 - timedelta`` | \(2) |
+---------------------------------------+-------------------------------+
| ``timedelta = datetime1 - datetime2`` | \(3) |
+---------------------------------------+-------------------------------+
| ``datetime1 < datetime2`` | Compares :class:`datetime` to |
| | :class:`datetime`. (4) |
+---------------------------------------+-------------------------------+
+---------------------------------------+--------------------------------+
| Operation | Result |
+=======================================+================================+
| ``datetime2 = datetime1 + timedelta`` | \(1) |
+---------------------------------------+--------------------------------+
| ``datetime2 = datetime1 - timedelta`` | \(2) |
+---------------------------------------+--------------------------------+
| ``timedelta = datetime1 - datetime2`` | \(3) |
+---------------------------------------+--------------------------------+
| ``datetime1 < datetime2`` | Compares :class:`.datetime` to |
| | :class:`.datetime`. (4) |
+---------------------------------------+--------------------------------+
(1)
datetime2 is a duration of timedelta removed from datetime1, moving forward in
@ -862,7 +862,7 @@ Supported operations:
in isolation can overflow in cases where datetime1 - timedelta does not.
(3)
Subtraction of a :class:`datetime` from a :class:`datetime` is defined only if
Subtraction of a :class:`.datetime` from a :class:`.datetime` is defined only if
both operands are naive, or if both are aware. If one is aware and the other is
naive, :exc:`TypeError` is raised.
@ -891,16 +891,16 @@ Supported operations:
In order to stop comparison from falling back to the default scheme of comparing
object addresses, datetime comparison normally raises :exc:`TypeError` if the
other comparand isn't also a :class:`datetime` object. However,
other comparand isn't also a :class:`.datetime` object. However,
``NotImplemented`` is returned instead if the other comparand has a
:meth:`timetuple` attribute. This hook gives other kinds of date objects a
chance at implementing mixed-type comparison. If not, when a :class:`datetime`
chance at implementing mixed-type comparison. If not, when a :class:`.datetime`
object is compared to an object of a different type, :exc:`TypeError` is raised
unless the comparison is ``==`` or ``!=``. The latter cases return
:const:`False` or :const:`True`, respectively.
:class:`datetime` objects can be used as dictionary keys. In Boolean contexts,
all :class:`datetime` objects are considered to be true.
:class:`.datetime` objects can be used as dictionary keys. In Boolean contexts,
all :class:`.datetime` objects are considered to be true.
Instance methods:
@ -911,13 +911,13 @@ Instance methods:
.. method:: datetime.time()
Return :class:`time` object with same hour, minute, second and microsecond.
Return :class:`.time` object with same hour, minute, second and microsecond.
:attr:`tzinfo` is ``None``. See also method :meth:`timetz`.
.. method:: datetime.timetz()
Return :class:`time` object with same hour, minute, second, microsecond, and
Return :class:`.time` object with same hour, minute, second, microsecond, and
tzinfo attributes. See also method :meth:`time`.
@ -931,7 +931,7 @@ Instance methods:
.. method:: datetime.astimezone(tz)
Return a :class:`datetime` object with new :attr:`tzinfo` attribute *tz*,
Return a :class:`.datetime` object with new :attr:`tzinfo` attribute *tz*,
adjusting the date and time data so the result is the same UTC time as
*self*, but in *tz*'s local time.
@ -1005,7 +1005,7 @@ Instance methods:
.. method:: datetime.utctimetuple()
If :class:`datetime` instance *d* is naive, this is the same as
If :class:`.datetime` instance *d* is naive, this is the same as
``d.timetuple()`` except that :attr:`tm_isdst` is forced to 0 regardless of what
``d.dst()`` returns. DST is never in effect for a UTC time.
@ -1066,7 +1066,7 @@ Instance methods:
.. method:: datetime.__str__()
For a :class:`datetime` instance *d*, ``str(d)`` is equivalent to
For a :class:`.datetime` instance *d*, ``str(d)`` is equivalent to
``d.isoformat(' ')``.
@ -1215,19 +1215,19 @@ Class attributes:
.. attribute:: time.min
The earliest representable :class:`time`, ``time(0, 0, 0, 0)``.
The earliest representable :class:`.time`, ``time(0, 0, 0, 0)``.
.. attribute:: time.max
The latest representable :class:`time`, ``time(23, 59, 59, 999999)``.
The latest representable :class:`.time`, ``time(23, 59, 59, 999999)``.
.. attribute:: time.resolution
The smallest possible difference between non-equal :class:`time` objects,
``timedelta(microseconds=1)``, although note that arithmetic on :class:`time`
objects is not supported.
The smallest possible difference between non-equal :class:`.time` objects,
``timedelta(microseconds=1)``, although note that arithmetic on
:class:`.time` objects is not supported.
Instance attributes (read-only):
@ -1254,13 +1254,13 @@ Instance attributes (read-only):
.. attribute:: time.tzinfo
The object passed as the tzinfo argument to the :class:`time` constructor, or
The object passed as the tzinfo argument to the :class:`.time` constructor, or
``None`` if none was passed.
Supported operations:
* comparison of :class:`time` to :class:`time`, where *a* is considered less
* comparison of :class:`.time` to :class:`.time`, where *a* is considered less
than *b* when *a* precedes *b* in time. If one comparand is naive and the other
is aware, :exc:`TypeError` is raised. If both comparands are aware, and have
the same :attr:`tzinfo` attribute, the common :attr:`tzinfo` attribute is
@ -1268,7 +1268,7 @@ Supported operations:
have different :attr:`tzinfo` attributes, the comparands are first adjusted by
subtracting their UTC offsets (obtained from ``self.utcoffset()``). In order
to stop mixed-type comparisons from falling back to the default comparison by
object address, when a :class:`time` object is compared to an object of a
object address, when a :class:`.time` object is compared to an object of a
different type, :exc:`TypeError` is raised unless the comparison is ``==`` or
``!=``. The latter cases return :const:`False` or :const:`True`, respectively.
@ -1276,7 +1276,7 @@ Supported operations:
* efficient pickling
* in Boolean contexts, a :class:`time` object is considered to be true if and
* in Boolean contexts, a :class:`.time` object is considered to be true if and
only if, after converting it to minutes and subtracting :meth:`utcoffset` (or
``0`` if that's ``None``), the result is non-zero.
@ -1285,10 +1285,10 @@ Instance methods:
.. method:: time.replace([hour[, minute[, second[, microsecond[, tzinfo]]]]])
Return a :class:`time` with the same value, except for those attributes given
Return a :class:`.time` with the same value, except for those attributes given
new values by whichever keyword arguments are specified. Note that
``tzinfo=None`` can be specified to create a naive :class:`time` from an
aware :class:`time`, without conversion of the time data.
``tzinfo=None`` can be specified to create a naive :class:`.time` from an
aware :class:`.time`, without conversion of the time data.
.. method:: time.isoformat()
@ -1366,13 +1366,13 @@ Example:
:class:`tzinfo` is an abstract base class, meaning that this class should not be
instantiated directly. You need to derive a concrete subclass, and (at least)
supply implementations of the standard :class:`tzinfo` methods needed by the
:class:`datetime` methods you use. The :mod:`datetime` module supplies
:class:`.datetime` methods you use. The :mod:`datetime` module supplies
a simple concrete subclass of :class:`tzinfo` :class:`timezone` which can reprsent
timezones with fixed offset from UTC such as UTC itself or North American EST and
EDT.
An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the
constructors for :class:`datetime` and :class:`time` objects. The latter objects
constructors for :class:`.datetime` and :class:`.time` objects. The latter objects
view their attributes as being in local time, and the :class:`tzinfo` object
supports methods revealing offset of local time from UTC, the name of the time
zone, and DST offset, all relative to a date or time object passed to them.
@ -1427,7 +1427,7 @@ methods. Exactly which methods are needed depends on the uses made of aware
``tz.utcoffset(dt) - tz.dst(dt)``
must return the same result for every :class:`datetime` *dt* with ``dt.tzinfo ==
must return the same result for every :class:`.datetime` *dt* with ``dt.tzinfo ==
tz`` For sane :class:`tzinfo` subclasses, this expression yields the time
zone's "standard offset", which should not depend on the date or the time, but
only on geographic location. The implementation of :meth:`datetime.astimezone`
@ -1459,7 +1459,7 @@ methods. Exactly which methods are needed depends on the uses made of aware
.. method:: tzinfo.tzname(dt)
Return the time zone name corresponding to the :class:`datetime` object *dt*, as
Return the time zone name corresponding to the :class:`.datetime` object *dt*, as
a string. Nothing about string names is defined by the :mod:`datetime` module,
and there's no requirement that it mean anything in particular. For example,
"GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" are all
@ -1472,11 +1472,11 @@ methods. Exactly which methods are needed depends on the uses made of aware
The default implementation of :meth:`tzname` raises :exc:`NotImplementedError`.
These methods are called by a :class:`datetime` or :class:`time` object, in
response to their methods of the same names. A :class:`datetime` object passes
itself as the argument, and a :class:`time` object passes ``None`` as the
These methods are called by a :class:`.datetime` or :class:`.time` object, in
response to their methods of the same names. A :class:`.datetime` object passes
itself as the argument, and a :class:`.time` object passes ``None`` as the
argument. A :class:`tzinfo` subclass's methods should therefore be prepared to
accept a *dt* argument of ``None``, or of class :class:`datetime`.
accept a *dt* argument of ``None``, or of class :class:`.datetime`.
When ``None`` is passed, it's up to the class designer to decide the best
response. For example, returning ``None`` is appropriate if the class wishes to
@ -1484,7 +1484,7 @@ say that time objects don't participate in the :class:`tzinfo` protocols. It
may be more useful for ``utcoffset(None)`` to return the standard UTC offset, as
there is no other convention for discovering the standard offset.
When a :class:`datetime` object is passed in response to a :class:`datetime`
When a :class:`.datetime` object is passed in response to a :class:`.datetime`
method, ``dt.tzinfo`` is the same object as *self*. :class:`tzinfo` methods can
rely on this, unless user code calls :class:`tzinfo` methods directly. The
intent is that the :class:`tzinfo` methods interpret *dt* as being in local
@ -1623,7 +1623,7 @@ made to civil time.
.. method:: timezone.fromutc(dt)
Return ``dt + offset``. The *dt* argument must be an aware
:class:`datetime` instance, with ``tzinfo`` set to ``self``.
:class:`.datetime` instance, with ``tzinfo`` set to ``self``.
Class attributes:
@ -1637,18 +1637,18 @@ Class attributes:
:meth:`strftime` and :meth:`strptime` Behavior
----------------------------------------------
:class:`date`, :class:`datetime`, and :class:`time` objects all support a
:class:`date`, :class:`.datetime`, and :class:`.time` objects all support a
``strftime(format)`` method, to create a string representing the time under the
control of an explicit format string. Broadly speaking, ``d.strftime(fmt)``
acts like the :mod:`time` module's ``time.strftime(fmt, d.timetuple())``
although not all objects support a :meth:`timetuple` method.
Conversely, the :meth:`datetime.strptime` class method creates a
:class:`datetime` object from a string representing a date and time and a
:class:`.datetime` object from a string representing a date and time and a
corresponding format string. ``datetime.strptime(date_string, format)`` is
equivalent to ``datetime(*(time.strptime(date_string, format)[0:6]))``.
For :class:`time` objects, the format codes for year, month, and day should not
For :class:`.time` objects, the format codes for year, month, and day should not
be used, as time objects have no such values. If they're used anyway, ``1900``
is substituted for the year, and ``1`` for the month and day.
@ -1806,5 +1806,5 @@ Notes:
.. versionchanged:: 3.2
When the ``%z`` directive is provided to the :meth:`strptime` method, an
aware :class:`datetime` object will be produced. The ``tzinfo`` of the
aware :class:`.datetime` object will be produced. The ``tzinfo`` of the
result will be set to a :class:`timezone` instance.