Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

merge from 3.2

This commit is contained in:
Senthil Kumaran 2011-07-17 19:06:03 +08:00
parent 87e59cd701 023c6f703d
commit 42d1320c06
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

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