[Python-checkins] cpython (2.7): Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@
sandro.tosi
python-checkins at python.org
Sat Feb 18 20:34:10 CET 2012
http://hg.python.org/cpython/rev/30ff707ed75f
changeset: 75021:30ff707ed75f
branch: 2.7
parent: 75015:0c02f30b2538
user: Sandro Tosi <sandro.tosi at gmail.com>
date: Sat Feb 18 20:28:35 2012 +0100
summary:
Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@
This is needed after the move to Sphinx 1.x and it's the same way 3.x braches
managed it.
files:
Doc/library/datetime.rst | 132 +++++++++++++-------------
1 files changed, 66 insertions(+), 66 deletions(-)
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -20,13 +20,13 @@
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
@@ -40,13 +40,13 @@
.. 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``.
@@ -90,14 +90,14 @@
.. 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).
@@ -105,7 +105,7 @@
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.
@@ -269,7 +269,7 @@
-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).
Comparisons of :class:`timedelta` objects are supported with the
@@ -602,10 +602,10 @@
: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:
@@ -653,7 +653,7 @@
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. See also :meth:`now`.
+ :class:`.datetime` object. See also :meth:`now`.
.. classmethod:: datetime.fromtimestamp(timestamp[, tz])
@@ -661,7 +661,7 @@
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
@@ -674,12 +674,12 @@
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
@@ -688,7 +688,7 @@
.. 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``.
@@ -696,18 +696,18 @@
.. 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
@@ -720,19 +720,19 @@
.. 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)``.
@@ -775,24 +775,24 @@
.. 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
@@ -811,7 +811,7 @@
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.
@@ -840,16 +840,16 @@
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:
@@ -860,13 +860,13 @@
.. 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`.
@@ -880,7 +880,7 @@
.. 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.
@@ -954,7 +954,7 @@
.. 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.
@@ -1015,7 +1015,7 @@
.. 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(' ')``.
@@ -1209,7 +1209,7 @@
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
@@ -1217,7 +1217,7 @@
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.
@@ -1225,7 +1225,7 @@
* 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.
@@ -1315,11 +1315,11 @@
: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 does not supply
+:class:`.datetime` methods you use. The :mod:`datetime` module does not supply
any concrete subclasses of :class:`tzinfo`.
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.
@@ -1374,7 +1374,7 @@
``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`
@@ -1406,7 +1406,7 @@
.. method:: tzinfo.tzname(self, 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
@@ -1419,11 +1419,11 @@
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
@@ -1431,7 +1431,7 @@
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
@@ -1527,18 +1527,18 @@
: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.
@@ -1547,7 +1547,7 @@
values. If they're used anyway, ``0`` is substituted for them.
.. versionadded:: 2.6
- :class:`time` and :class:`datetime` objects support a ``%f`` format code
+ :class:`.time` and :class:`.datetime` objects support a ``%f`` format code
which expands to the number of microseconds in the object, zero-padded on
the left to six places.
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list