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

merge from 3.2 - Issue10403 - datetime module documentation changes based on review.

This commit is contained in:
Senthil Kumaran 2011-07-17 19:10:10 +08:00
parent a09f13a0bc
commit 4c9721ad40
1 changed files with 20 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
Doc/library/datetime.rst
View File

@ -27,8 +27,8 @@ 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
have an optional time zone information attribute, :attr:`tzinfo`, that can contain
an instance of a subclass of the abstract :class:`tzinfo` class. These
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
time zone name, and whether Daylight Saving Time is in effect. Note that no
concrete :class:`tzinfo` classes are supplied by the :mod:`datetime` module.
@ -696,11 +696,13 @@ Other constructors, all class methods:
.. classmethod:: datetime.combine(date, time)
Return a new :class:`datetime` object whose date attributes are equal to the
given :class:`date` object's, and whose time and :attr:`tzinfo` 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 and :attr:`tzinfo` attributes are ignored.
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*,
``d == datetime.combine(d.date(), d.timetz())``. If date is a
:class:`datetime` object, its time components and :attr:`tzinfo` attributes
are ignored.
.. classmethod:: datetime.strptime(date_string, format)
@ -873,13 +875,13 @@ Instance methods:
Return a datetime with the same attributes, except for those attributes given
new values by whichever keyword arguments are specified. Note that
``tzinfo=None`` can be specified to create a naive datetime from an aware
datetime with no conversion of date and time attributes.
datetime with no conversion of date and time data.
.. method:: datetime.astimezone(tz)
Return a :class:`datetime` object with new :attr:`tzinfo` attribute *tz*,
adjusting the date and time attributes so the result is the same UTC time as
adjusting the date and time data so the result is the same UTC time as
*self*, but in *tz*'s local time.
*tz* must be an instance of a :class:`tzinfo` subclass, and its
@ -888,18 +890,18 @@ Instance methods:
not return ``None``).
If ``self.tzinfo`` is *tz*, ``self.astimezone(tz)`` is equal to *self*: no
adjustment of date or time attributes is performed. Else the result is local
adjustment of date or time data is performed. Else the result is local
time in time zone *tz*, representing the same UTC time as *self*: after
``astz = dt.astimezone(tz)``, ``astz - astz.utcoffset()`` will usually have
the same date and time attributes as ``dt - dt.utcoffset()``. The discussion
the same date and time data as ``dt - dt.utcoffset()``. The discussion
of class :class:`tzinfo` explains the cases at Daylight Saving Time transition
boundaries where this cannot be achieved (an issue only if *tz* models both
standard and daylight time).
If you merely want to attach a time zone object *tz* to a datetime *dt* without
adjustment of date and time attributes, use ``dt.replace(tzinfo=tz)``. If you
adjustment of date and time data, use ``dt.replace(tzinfo=tz)``. If you
merely want to remove the time zone object from an aware datetime *dt* without
conversion of date and time attributes, use ``dt.replace(tzinfo=None)``.
conversion of date and time data, use ``dt.replace(tzinfo=None)``.
Note that the default :meth:`tzinfo.fromutc` method can be overridden in a
:class:`tzinfo` subclass to affect the result returned by :meth:`astimezone`.
@ -1235,7 +1237,7 @@ Instance methods:
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 attributes.
aware :class:`time`, without conversion of the time data.
.. method:: time.isoformat()
@ -1440,10 +1442,10 @@ There is one more :class:`tzinfo` method that a subclass may wish to override:
.. method:: tzinfo.fromutc(self, dt)
This is called from the default :class:`datetime.astimezone()` implementation.
When called from that, ``dt.tzinfo`` is *self*, and *dt*'s date and time
attributes are to be viewed as expressing a UTC time. The purpose of
:meth:`fromutc` is to adjust the date and time attributes, returning an
This is called from the default :class:`datetime.astimezone()`
implementation. When called from that, ``dt.tzinfo`` is *self*, and *dt*'s
date and time data are to be viewed as expressing a UTC time. The purpose
of :meth:`fromutc` is to adjust the date and time data, returning an
equivalent datetime in *self*'s local time.
Most :class:`tzinfo` subclasses should be able to inherit the default