cpython-lru_cache-weakref: Doc/library/datetime.rst annotate

annotate Doc/library/datetime.rst @ 79675:c0a2294de787 2.7

Issue #16199: Backport 2to3 typo fix from 3.2.

author	Chris Jerdonek <chris.jerdonek@gmail.com>
date	Thu, 11 Oct 2012 16:15:46 -0700
parents	c1c45755397b
children	0fd2ea06e17d

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 :mod:`datetime` --- Basic date and time types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 =============================================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 .. module:: datetime
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 :synopsis: Basic date and time types.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6 .. moduleauthor:: Tim Peters <tim@zope.com>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 .. sectionauthor:: Tim Peters <tim@zope.com>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 .. sectionauthor:: A.M. Kuchling <amk@amk.ca>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44221 diff changeset	10 .. XXX what order should the types be discussed in?
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 The :mod:`datetime` module supplies classes for manipulating dates and times in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 both simple and complex ways. While date and time arithmetic is supported, the
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	16 focus of the implementation is on efficient attribute extraction for output
76941 a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	17 formatting and manipulation. For related functionality, see also the
a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	18 :mod:`time` and :mod:`calendar` modules.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19
76940 5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	20 There are two kinds of date and time objects: "naive" and "aware".
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	21
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	22 An aware object has sufficient knowledge of applicable algorithmic and
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	23 political time adjustments, such as time zone and daylight saving time
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	24 information, to locate itself relative to other aware objects. An aware object
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	25 is used to represent a specific moment in time that is not open to
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	26 interpretation [#]_.
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	27
78698 c1c45755397b Remove patch artifacts. Georg Brandl <georg@python.org> parents: 77806 diff changeset	28 A naive object does not contain enough information to unambiguously locate
c1c45755397b Remove patch artifacts. Georg Brandl <georg@python.org> parents: 77806 diff changeset	29 itself relative to other date/time objects. Whether a naive object represents
76941 a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	30 Coordinated Universal Time (UTC), local time, or time in some other timezone is
a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	31 purely up to the program, just like it's up to the program whether a particular
a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	32 number represents metres, miles, or mass. Naive objects are easy to understand
a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	33 and to work with, at the cost of ignoring some aspects of reality.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34
76941 a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	35 For applications requiring aware objects, :class:`.datetime` and :class:`.time`
a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	36 objects have an optional time zone information attribute, :attr:`tzinfo`, that
a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	37 can be set to an instance of a subclass of the abstract :class:`tzinfo` class.
a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	38 These :class:`tzinfo` objects capture information about the offset from UTC
a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	39 time, the time zone name, and whether Daylight Saving Time is in effect. Note
a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	40 that no concrete :class:`tzinfo` classes are supplied by the :mod:`datetime`
a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	41 module. Supporting timezones at whatever level of detail is required is up to
a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	42 the application. The rules for time adjustment across the world are more
a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	43 political than rational, and there is no standard suitable for every
a002638919d8 #14766: Reflow the altered paragraphs. R David Murray <rdmurray@bitdance.com> parents: 76940 diff changeset	44 application.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 The :mod:`datetime` module exports the following constants:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 .. data:: MINYEAR
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	50 The smallest year number allowed in a :class:`date` or :class:`.datetime` object.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 :const:`MINYEAR` is ``1``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 .. data:: MAXYEAR
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	56 The largest year number allowed in a :class:`date` or :class:`.datetime` object.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57 :const:`MAXYEAR` is ``9999``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 .. seealso::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 Module :mod:`calendar`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 General calendar related functions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 Module :mod:`time`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 Time access and conversions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 Available Types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 ---------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 .. class:: date
56822 c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 52725 diff changeset	73 :noindex:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 An idealized naive date, assuming the current Gregorian calendar always was, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 always will be, in effect. Attributes: :attr:`year`, :attr:`month`, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 :attr:`day`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 .. class:: time
56822 c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 52725 diff changeset	81 :noindex:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83 An idealized time, independent of any particular day, assuming that every day
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 has exactly 24\60\60 seconds (there is no notion of "leap seconds" here).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 Attributes: :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86 and :attr:`tzinfo`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 .. class:: datetime
56822 c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 52725 diff changeset	90 :noindex:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 A combination of a date and a time. Attributes: :attr:`year`, :attr:`month`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 :attr:`day`, :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 and :attr:`tzinfo`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 .. class:: timedelta
56822 c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 52725 diff changeset	98 :noindex:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	100 A duration expressing the difference between two :class:`date`, :class:`.time`,
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	101 or :class:`.datetime` instances to microsecond resolution.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 .. class:: tzinfo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 An abstract base class for time zone information objects. These are used by the
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	107 :class:`.datetime` and :class:`.time` classes to provide a customizable notion of
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 time adjustment (for example, to account for time zone and/or daylight saving
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 time).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 Objects of these types are immutable.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 Objects of the :class:`date` type are always naive.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114
76940 5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	115 An object of type :class:`.time` or :class:`.datetime` may be naive or aware.
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	116 A :class:`.datetime` object d is aware if ``d.tzinfo`` is not ``None`` and
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	117 ``d.tzinfo.utcoffset(d)`` does not return ``None``. If ``d.tzinfo`` is
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	118 ``None``, or if ``d.tzinfo`` is not ``None`` but ``d.tzinfo.utcoffset(d)``
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	119 returns ``None``, d is naive. A :class:`.time` object t is aware
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	120 if ``t.tzinfo`` is not ``None`` and ``t.tzinfo.utcoffset(None)`` does not return
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	121 ``None``. Otherwise, t is naive.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 The distinction between naive and aware doesn't apply to :class:`timedelta`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 objects.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 Subclass relationships::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 object
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129 timedelta
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 tzinfo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131 time
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 date
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 datetime
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 .. _datetime-timedelta:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 :class:`timedelta` Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 --------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 A :class:`timedelta` object represents a duration, the difference between two
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 dates or times.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 .. class:: timedelta([days[, seconds[, microseconds[, milliseconds[, minutes[, hours[, weeks]]]]]]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 All arguments are optional and default to ``0``. Arguments may be ints, longs,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147 or floats, and may be positive or negative.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149 Only days, seconds and microseconds are stored internally. Arguments are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 converted to those units:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 * A millisecond is converted to 1000 microseconds.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 * A minute is converted to 60 seconds.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 * An hour is converted to 3600 seconds.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 * A week is converted to 7 days.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 and days, seconds and microseconds are then normalized so that the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158 representation is unique, with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 * ``0 <= microseconds < 1000000``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 * ``0 <= seconds < 3600*24`` (the number of seconds in one day)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 * ``-999999999 <= days <= 999999999``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164 If any argument is a float and there are fractional microseconds, the fractional
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165 microseconds left over from all arguments are combined and their sum is rounded
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166 to the nearest microsecond. If no argument is a float, the conversion and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 normalization processes are exact (no information is lost).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 If the normalized value of days lies outside the indicated range,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170 :exc:`OverflowError` is raised.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172 Note that normalization of negative values may be surprising at first. For
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	173 example,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	175 >>> from datetime import timedelta
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176 >>> d = timedelta(microseconds=-1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177 >>> (d.days, d.seconds, d.microseconds)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178 (-1, 86399, 999999)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	180
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181 Class attributes are:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 .. attribute:: timedelta.min
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185 The most negative :class:`timedelta` object, ``timedelta(-999999999)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 .. attribute:: timedelta.max
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190 The most positive :class:`timedelta` object, ``timedelta(days=999999999,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191 hours=23, minutes=59, seconds=59, microseconds=999999)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194 .. attribute:: timedelta.resolution
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196 The smallest possible difference between non-equal :class:`timedelta` objects,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 ``timedelta(microseconds=1)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 Note that, because of normalization, ``timedelta.max`` > ``-timedelta.min``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 ``-timedelta.max`` is not representable as a :class:`timedelta` object.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202 Instance attributes (read-only):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204 +------------------+--------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 \| Attribute \| Value \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206 +==================+============================================+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 \| ``days`` \| Between -999999999 and 999999999 inclusive \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 +------------------+--------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 \| ``seconds`` \| Between 0 and 86399 inclusive \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 +------------------+--------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211 \| ``microseconds`` \| Between 0 and 999999 inclusive \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 +------------------+--------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214 Supported operations:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44221 diff changeset	216 .. XXX this table is too wide!
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 +--------------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 \| Operation \| Result \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 +================================+===============================================+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221 \| ``t1 = t2 + t3`` \| Sum of t2 and t3. Afterwards t1-t2 == \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222 \| \| t3 and t1-t3 == t2 are true. (1) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223 +--------------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 \| ``t1 = t2 - t3`` \| Difference of t2 and t3. Afterwards t1 \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 \| \| == t2 - t3 and t2 == t1 + t3 are \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 \| \| true. (1) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227 +--------------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 \| ``t1 = t2 * i or t1 = i * t2`` \| Delta multiplied by an integer or long. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 \| \| Afterwards t1 // i == t2 is true, \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 \| \| provided ``i != 0``. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 +--------------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232 \| \| In general, t1 \* i == t1 \* (i-1) + t1 \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 \| \| is true. (1) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 +--------------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 \| ``t1 = t2 // i`` \| The floor is computed and the remainder (if \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 \| \| any) is thrown away. (3) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 +--------------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238 \| ``+t1`` \| Returns a :class:`timedelta` object with the \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 \| \| same value. (2) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 +--------------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 \| ``-t1`` \| equivalent to :class:`timedelta`\ \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 \| \| (-t1.days, -t1.seconds, \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 \| \| -t1.microseconds), and to t1\* -1. (1)(4) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 +--------------------------------+-----------------------------------------------+
56824 b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56822 diff changeset	245 \| ``abs(t)`` \| equivalent to +\ t when ``t.days >= 0``, and\|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 \| \| to -t when ``t.days < 0``. (2) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 +--------------------------------+-----------------------------------------------+
63512 9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	248 \| ``str(t)`` \| Returns a string in the form \|
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	249 \| \| ``[D day[s], ][H]H:MM:SS[.UUUUUU]``, where D \|
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	250 \| \| is negative for negative ``t``. (5) \|
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	251 +--------------------------------+-----------------------------------------------+
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	252 \| ``repr(t)`` \| Returns a string in the form \|
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	253 \| \| ``datetime.timedelta(D[, S[, U]])``, where D \|
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	254 \| \| is negative for negative ``t``. (5) \|
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	255 +--------------------------------+-----------------------------------------------+
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257 Notes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259 (1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 This is exact, but may overflow.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 (2)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 This is exact, and cannot overflow.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265 (3)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 Division by 0 raises :exc:`ZeroDivisionError`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268 (4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269 -timedelta.max is not representable as a :class:`timedelta` object.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270
63512 9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	271 (5)
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	272 String representations of :class:`timedelta` objects are normalized
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	273 similarly to their internal representation. This leads to somewhat
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	274 unusual results for negative timedeltas. For example:
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	275
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	276 >>> timedelta(hours=-5)
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	277 datetime.timedelta(-1, 68400)
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	278 >>> print(_)
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	279 -1 day, 19:00:00
9c75a94187c7 Merged revisions 82793-82794,82807,82876,83432 via svnmerge from Georg Brandl <georg@python.org> parents: 59845 diff changeset	280
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281 In addition to the operations listed above :class:`timedelta` objects support
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	282 certain additions and subtractions with :class:`date` and :class:`.datetime`
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283 objects (see below).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285 Comparisons of :class:`timedelta` objects are supported with the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 :class:`timedelta` object representing the smaller duration considered to be the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 smaller timedelta. In order to stop mixed-type comparisons from falling back to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288 the default comparison by object address, when a :class:`timedelta` object is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 compared to an object of a different type, :exc:`TypeError` is raised unless the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290 comparison is ``==`` or ``!=``. The latter cases return :const:`False` or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291 :const:`True`, respectively.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292
43753 4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 42604 diff changeset	293 :class:`timedelta` objects are :term:`hashable` (usable as dictionary keys), support
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 efficient pickling, and in Boolean contexts, a :class:`timedelta` object is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295 considered to be true if and only if it isn't equal to ``timedelta(0)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296
57461 a6981f4a74a1 Issue #5788: `datetime.timedelta` objects get a new `total_seconds()` method returning Antoine Pitrou <solipsis@pitrou.net> parents: 57091 diff changeset	297 Instance methods:
a6981f4a74a1 Issue #5788: `datetime.timedelta` objects get a new `total_seconds()` method returning Antoine Pitrou <solipsis@pitrou.net> parents: 57091 diff changeset	298
a6981f4a74a1 Issue #5788: `datetime.timedelta` objects get a new `total_seconds()` method returning Antoine Pitrou <solipsis@pitrou.net> parents: 57091 diff changeset	299 .. method:: timedelta.total_seconds()
a6981f4a74a1 Issue #5788: `datetime.timedelta` objects get a new `total_seconds()` method returning Antoine Pitrou <solipsis@pitrou.net> parents: 57091 diff changeset	300
61454 6a2d0cc7d604 Issue #8644: Improve accuracy of timedelta.total_seconds method. Mark Dickinson <dickinsm@gmail.com> parents: 59802 diff changeset	301 Return the total number of seconds contained in the duration.
6a2d0cc7d604 Issue #8644: Improve accuracy of timedelta.total_seconds method. Mark Dickinson <dickinsm@gmail.com> parents: 59802 diff changeset	302 Equivalent to ``(td.microseconds + (td.seconds + td.days * 24 *
6a2d0cc7d604 Issue #8644: Improve accuracy of timedelta.total_seconds method. Mark Dickinson <dickinsm@gmail.com> parents: 59802 diff changeset	303 3600) * 106) / 106`` computed with true division enabled.
6a2d0cc7d604 Issue #8644: Improve accuracy of timedelta.total_seconds method. Mark Dickinson <dickinsm@gmail.com> parents: 59802 diff changeset	304
6a2d0cc7d604 Issue #8644: Improve accuracy of timedelta.total_seconds method. Mark Dickinson <dickinsm@gmail.com> parents: 59802 diff changeset	305 Note that for very large time intervals (greater than 270 years on
6a2d0cc7d604 Issue #8644: Improve accuracy of timedelta.total_seconds method. Mark Dickinson <dickinsm@gmail.com> parents: 59802 diff changeset	306 most platforms) this method will lose microsecond accuracy.
57461 a6981f4a74a1 Issue #5788: `datetime.timedelta` objects get a new `total_seconds()` method returning Antoine Pitrou <solipsis@pitrou.net> parents: 57091 diff changeset	307
57463 61e6ce718500 Forgot to add a `versionadded` tag Antoine Pitrou <solipsis@pitrou.net> parents: 57461 diff changeset	308 .. versionadded:: 2.7
61e6ce718500 Forgot to add a `versionadded` tag Antoine Pitrou <solipsis@pitrou.net> parents: 57461 diff changeset	309
57461 a6981f4a74a1 Issue #5788: `datetime.timedelta` objects get a new `total_seconds()` method returning Antoine Pitrou <solipsis@pitrou.net> parents: 57091 diff changeset	310
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	311 Example usage:
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	312
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	313 >>> from datetime import timedelta
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	314 >>> year = timedelta(days=365)
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	315 >>> another_year = timedelta(weeks=40, days=84, hours=23,
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	316 ... minutes=50, seconds=600) # adds up to 365 days
57461 a6981f4a74a1 Issue #5788: `datetime.timedelta` objects get a new `total_seconds()` method returning Antoine Pitrou <solipsis@pitrou.net> parents: 57091 diff changeset	317 >>> year.total_seconds()
a6981f4a74a1 Issue #5788: `datetime.timedelta` objects get a new `total_seconds()` method returning Antoine Pitrou <solipsis@pitrou.net> parents: 57091 diff changeset	318 31536000.0
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	319 >>> year == another_year
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	320 True
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	321 >>> ten_years = 10 * year
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	322 >>> ten_years, ten_years.days // 365
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	323 (datetime.timedelta(3650), 10)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	324 >>> nine_years = ten_years - year
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	325 >>> nine_years, nine_years.days // 365
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	326 (datetime.timedelta(3285), 9)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	327 >>> three_years = nine_years // 3;
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	328 >>> three_years, three_years.days // 365
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	329 (datetime.timedelta(1095), 3)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	330 >>> abs(three_years - ten_years) == 2 * three_years + year
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	331 True
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	332
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334 .. _datetime-date:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 :class:`date` Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337 ---------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339 A :class:`date` object represents a date (year, month and day) in an idealized
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340 calendar, the current Gregorian calendar indefinitely extended in both
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341 directions. January 1 of year 1 is called day number 1, January 2 of year 1 is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 called day number 2, and so on. This matches the definition of the "proleptic
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343 Gregorian" calendar in Dershowitz and Reingold's book Calendrical Calculations,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 where it's the base calendar for all computations. See the book for algorithms
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 for converting between proleptic Gregorian ordinals and many other calendar
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346 systems.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349 .. class:: date(year, month, day)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	351 All arguments are required. Arguments may be ints or longs, in the following
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352 ranges:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354 * ``MINYEAR <= year <= MAXYEAR``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355 * ``1 <= month <= 12``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 * ``1 <= day <= number of days in the given month and year``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 If an argument outside those ranges is given, :exc:`ValueError` is raised.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	360
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361 Other constructors, all class methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	363 .. classmethod:: date.today()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365 Return the current local date. This is equivalent to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366 ``date.fromtimestamp(time.time())``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	369 .. classmethod:: date.fromtimestamp(timestamp)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371 Return the local date corresponding to the POSIX timestamp, such as is returned
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372 by :func:`time.time`. This may raise :exc:`ValueError`, if the timestamp is out
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 73269 diff changeset	373 of the range of values supported by the platform C :c:func:`localtime` function.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374 It's common for this to be restricted to years from 1970 through 2038. Note
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375 that on non-POSIX systems that include leap seconds in their notion of a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376 timestamp, leap seconds are ignored by :meth:`fromtimestamp`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	377
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	379 .. classmethod:: date.fromordinal(ordinal)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 Return the date corresponding to the proleptic Gregorian ordinal, where January
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1 <= ordinal <=
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383 date.max.toordinal()``. For any date d, ``date.fromordinal(d.toordinal()) ==
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384 d``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	386
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387 Class attributes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389 .. attribute:: date.min
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391 The earliest representable date, ``date(MINYEAR, 1, 1)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394 .. attribute:: date.max
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396 The latest representable date, ``date(MAXYEAR, 12, 31)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399 .. attribute:: date.resolution
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401 The smallest possible difference between non-equal date objects,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 ``timedelta(days=1)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	404
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405 Instance attributes (read-only):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407 .. attribute:: date.year
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409 Between :const:`MINYEAR` and :const:`MAXYEAR` inclusive.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412 .. attribute:: date.month
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414 Between 1 and 12 inclusive.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417 .. attribute:: date.day
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419 Between 1 and the number of days in the given month of the given year.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	421
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422 Supported operations:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	424 +-------------------------------+----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425 \| Operation \| Result \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 +===============================+==============================================+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427 \| ``date2 = date1 + timedelta`` \| date2 is ``timedelta.days`` days removed \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428 \| \| from date1. (1) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429 +-------------------------------+----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430 \| ``date2 = date1 - timedelta`` \| Computes date2 such that ``date2 + \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431 \| \| timedelta == date1``. (2) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432 +-------------------------------+----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433 \| ``timedelta = date1 - date2`` \| \(3) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434 +-------------------------------+----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435 \| ``date1 < date2`` \| date1 is considered less than date2 when \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	436 \| \| date1 precedes date2 in time. (4) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437 +-------------------------------+----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439 Notes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	440
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 (1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	442 date2 is moved forward in time if ``timedelta.days > 0``, or backward if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443 ``timedelta.days < 0``. Afterward ``date2 - date1 == timedelta.days``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444 ``timedelta.seconds`` and ``timedelta.microseconds`` are ignored.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445 :exc:`OverflowError` is raised if ``date2.year`` would be smaller than
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446 :const:`MINYEAR` or larger than :const:`MAXYEAR`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	447
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	448 (2)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	449 This isn't quite equivalent to date1 + (-timedelta), because -timedelta in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450 isolation can overflow in cases where date1 - timedelta does not.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451 ``timedelta.seconds`` and ``timedelta.microseconds`` are ignored.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453 (3)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 This is exact, and cannot overflow. timedelta.seconds and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455 timedelta.microseconds are 0, and date2 + timedelta == date1 after.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457 (4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458 In other words, ``date1 < date2`` if and only if ``date1.toordinal() <
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459 date2.toordinal()``. In order to stop comparison from falling back to the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460 default scheme of comparing object addresses, date comparison normally raises
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461 :exc:`TypeError` if the other comparand isn't also a :class:`date` object.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462 However, ``NotImplemented`` is returned instead if the other comparand has a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463 :meth:`timetuple` attribute. This hook gives other kinds of date objects a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	464 chance at implementing mixed-type comparison. If not, when a :class:`date`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	465 object is compared to an object of a different type, :exc:`TypeError` is raised
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466 unless the comparison is ``==`` or ``!=``. The latter cases return
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 :const:`False` or :const:`True`, respectively.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469 Dates can be used as dictionary keys. In Boolean contexts, all :class:`date`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	470 objects are considered to be true.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472 Instance methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	473
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474 .. method:: date.replace(year, month, day)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	476 Return a date with the same value, except for those parameters given new
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	477 values by whichever keyword arguments are specified. For example, if ``d ==
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	478 date(2002, 12, 31)``, then ``d.replace(day=26) == date(2002, 12, 26)``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481 .. method:: date.timetuple()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483 Return a :class:`time.struct_time` such as returned by :func:`time.localtime`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484 The hours, minutes and seconds are 0, and the DST flag is -1. ``d.timetuple()``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485 is equivalent to ``time.struct_time((d.year, d.month, d.day, 0, 0, 0,
61876 21fa09f250e3 #1436346: make it more obvious that timetuple[7] is yday. Georg Brandl <georg@python.org> parents: 61454 diff changeset	486 d.weekday(), yday, -1))``, where ``yday = d.toordinal() - date(d.year, 1,
21fa09f250e3 #1436346: make it more obvious that timetuple[7] is yday. Georg Brandl <georg@python.org> parents: 61454 diff changeset	487 1).toordinal() + 1`` is the day number within the current year starting with
21fa09f250e3 #1436346: make it more obvious that timetuple[7] is yday. Georg Brandl <georg@python.org> parents: 61454 diff changeset	488 ``1`` for January 1st.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491 .. method:: date.toordinal()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493 Return the proleptic Gregorian ordinal of the date, where January 1 of year 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494 has ordinal 1. For any :class:`date` object d,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495 ``date.fromordinal(d.toordinal()) == d``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498 .. method:: date.weekday()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	500 Return the day of the week as an integer, where Monday is 0 and Sunday is 6.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	501 For example, ``date(2002, 12, 4).weekday() == 2``, a Wednesday. See also
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502 :meth:`isoweekday`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505 .. method:: date.isoweekday()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507 Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508 For example, ``date(2002, 12, 4).isoweekday() == 3``, a Wednesday. See also
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509 :meth:`weekday`, :meth:`isocalendar`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	511
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512 .. method:: date.isocalendar()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514 Return a 3-tuple, (ISO year, ISO week number, ISO weekday).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516 The ISO calendar is a widely used variant of the Gregorian calendar. See
57092 92cc7ed83e9c Merged revisions 76082 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 57087 diff changeset	517 http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm for a good
92cc7ed83e9c Merged revisions 76082 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 57087 diff changeset	518 explanation.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	520 The ISO year consists of 52 or 53 full weeks, and where a week starts on a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521 Monday and ends on a Sunday. The first week of an ISO year is the first
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	522 (Gregorian) calendar week of a year containing a Thursday. This is called week
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	523 number 1, and the ISO year of that Thursday is the same as its Gregorian year.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	524
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	525 For example, 2004 begins on a Thursday, so the first week of ISO year 2004
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	526 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan 2004, so that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	527 ``date(2003, 12, 29).isocalendar() == (2004, 1, 1)`` and ``date(2004, 1,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	528 4).isocalendar() == (2004, 1, 7)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	530
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	531 .. method:: date.isoformat()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	532
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	533 Return a string representing the date in ISO 8601 format, 'YYYY-MM-DD'. For
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534 example, ``date(2002, 12, 4).isoformat() == '2002-12-04'``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537 .. method:: date.__str__()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539 For a date d, ``str(d)`` is equivalent to ``d.isoformat()``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542 .. method:: date.ctime()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544 Return a string representing the date, for example ``date(2002, 12,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 4).ctime() == 'Wed Dec 4 00:00:00 2002'``. ``d.ctime()`` is equivalent to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546 ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the native C
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 73269 diff changeset	547 :c:func:`ctime` function (which :func:`time.ctime` invokes, but which
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548 :meth:`date.ctime` does not invoke) conforms to the C standard.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551 .. method:: date.strftime(format)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	552
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553 Return a string representing the date, controlled by an explicit format string.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554 Format codes referring to hours, minutes or seconds will see 0 values. See
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	555 section :ref:`strftime-strptime-behavior`.
9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	556
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	557
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	558 Example of counting days to an event::
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	559
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	560 >>> import time
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	561 >>> from datetime import date
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	562 >>> today = date.today()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	563 >>> today
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	564 datetime.date(2007, 12, 5)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	565 >>> today == date.fromtimestamp(time.time())
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	566 True
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	567 >>> my_birthday = date(today.year, 6, 24)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	568 >>> if my_birthday < today:
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	569 ... my_birthday = my_birthday.replace(year=today.year + 1)
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	570 >>> my_birthday
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	571 datetime.date(2008, 6, 24)
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	572 >>> time_to_birthday = abs(my_birthday - today)
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	573 >>> time_to_birthday.days
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	574 202
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	575
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	576 Example of working with :class:`date`:
f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	577
f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	578 .. doctest::
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	579
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	580 >>> from datetime import date
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	581 >>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	582 >>> d
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	583 datetime.date(2002, 3, 11)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	584 >>> t = d.timetuple()
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	585 >>> for i in t: # doctest: +SKIP
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	586 ... print i
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	587 2002 # year
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	588 3 # month
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	589 11 # day
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	590 0
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	591 0
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	592 0
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	593 0 # weekday (0 = Monday)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	594 70 # 70th day in the year
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	595 -1
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	596 >>> ic = d.isocalendar()
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	597 >>> for i in ic: # doctest: +SKIP
f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	598 ... print i
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	599 2002 # ISO year
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	600 11 # ISO week number
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	601 1 # ISO day number ( 1 = Monday )
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	602 >>> d.isoformat()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	603 '2002-03-11'
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	604 >>> d.strftime("%d/%m/%y")
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	605 '11/03/02'
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	606 >>> d.strftime("%A %d. %B %Y")
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	607 'Monday 11. March 2002'
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	608
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	609
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	610 .. _datetime-datetime:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	611
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	612 :class:`datetime` Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	613 -------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	614
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	615 A :class:`.datetime` object is a single object containing all the information
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	616 from a :class:`date` object and a :class:`.time` object. Like a :class:`date`
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	617 object, :class:`.datetime` assumes the current Gregorian calendar extended in
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	618 both directions; like a time object, :class:`.datetime` assumes there are exactly
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	619 3600\*24 seconds in every day.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	620
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	621 Constructor:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	622
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	623 .. class:: datetime(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	624
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	625 The year, month and day arguments are required. tzinfo may be ``None``, or an
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	626 instance of a :class:`tzinfo` subclass. The remaining arguments may be ints or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	627 longs, in the following ranges:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	628
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	629 * ``MINYEAR <= year <= MAXYEAR``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	630 * ``1 <= month <= 12``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	631 * ``1 <= day <= number of days in the given month and year``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632 * ``0 <= hour < 24``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	633 * ``0 <= minute < 60``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	634 * ``0 <= second < 60``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	635 * ``0 <= microsecond < 1000000``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	636
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	637 If an argument outside those ranges is given, :exc:`ValueError` is raised.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	638
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	639 Other constructors, all class methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	640
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	641 .. classmethod:: datetime.today()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	642
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	643 Return the current local datetime, with :attr:`tzinfo` ``None``. This is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	644 equivalent to ``datetime.fromtimestamp(time.time())``. See also :meth:`now`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	645 :meth:`fromtimestamp`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	646
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	647
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	648 .. classmethod:: datetime.now([tz])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	649
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	650 Return the current local date and time. If optional argument tz is ``None``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	651 or not specified, this is like :meth:`today`, but, if possible, supplies more
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	652 precision than can be gotten from going through a :func:`time.time` timestamp
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653 (for example, this may be possible on platforms supplying the C
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 73269 diff changeset	654 :c:func:`gettimeofday` function).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	655
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656 Else tz must be an instance of a class :class:`tzinfo` subclass, and the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	657 current date and time are converted to tz's time zone. In this case the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	658 result is equivalent to ``tz.fromutc(datetime.utcnow().replace(tzinfo=tz))``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	659 See also :meth:`today`, :meth:`utcnow`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	660
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	661
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	662 .. classmethod:: datetime.utcnow()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	663
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664 Return the current UTC date and time, with :attr:`tzinfo` ``None``. This is like
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665 :meth:`now`, but returns the current UTC date and time, as a naive
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	666 :class:`.datetime` object. See also :meth:`now`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	667
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	668
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	669 .. classmethod:: datetime.fromtimestamp(timestamp[, tz])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671 Return the local date and time corresponding to the POSIX timestamp, such as is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672 returned by :func:`time.time`. If optional argument tz is ``None`` or not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	673 specified, the timestamp is converted to the platform's local date and time, and
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	674 the returned :class:`.datetime` object is naive.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	676 Else tz must be an instance of a class :class:`tzinfo` subclass, and the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	677 timestamp is converted to tz's time zone. In this case the result is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	678 equivalent to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679 ``tz.fromutc(datetime.utcfromtimestamp(timestamp).replace(tzinfo=tz))``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	680
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	681 :meth:`fromtimestamp` may raise :exc:`ValueError`, if the timestamp is out of
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 73269 diff changeset	682 the range of values supported by the platform C :c:func:`localtime` or
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 73269 diff changeset	683 :c:func:`gmtime` functions. It's common for this to be restricted to years in
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	684 1970 through 2038. Note that on non-POSIX systems that include leap seconds in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	685 their notion of a timestamp, leap seconds are ignored by :meth:`fromtimestamp`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	686 and then it's possible to have two timestamps differing by a second that yield
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	687 identical :class:`.datetime` objects. See also :meth:`utcfromtimestamp`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	688
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	689
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	690 .. classmethod:: datetime.utcfromtimestamp(timestamp)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	691
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	692 Return the UTC :class:`.datetime` corresponding to the POSIX timestamp, with
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	693 :attr:`tzinfo` ``None``. This may raise :exc:`ValueError`, if the timestamp is
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 73269 diff changeset	694 out of the range of values supported by the platform C :c:func:`gmtime` function.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	695 It's common for this to be restricted to years in 1970 through 2038. See also
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	696 :meth:`fromtimestamp`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	697
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	699 .. classmethod:: datetime.fromordinal(ordinal)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	701 Return the :class:`.datetime` corresponding to the proleptic Gregorian ordinal,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702 where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	703 <= ordinal <= datetime.max.toordinal()``. The hour, minute, second and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704 microsecond of the result are all 0, and :attr:`tzinfo` is ``None``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	706
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	707 .. classmethod:: datetime.combine(date, time)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	708
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	709 Return a new :class:`.datetime` object whose date components are equal to the
71387 3935a1fb1db2 merge from 3.2 - Issue10403 - datetime module documentation changes based on review. Senthil Kumaran <senthil@uthcode.com> parents: 71212 diff changeset	710 given :class:`date` object's, and whose time components and :attr:`tzinfo`
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	711 attributes are equal to the given :class:`.time` object's. For any
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	712 :class:`.datetime` object d,
71387 3935a1fb1db2 merge from 3.2 - Issue10403 - datetime module documentation changes based on review. Senthil Kumaran <senthil@uthcode.com> parents: 71212 diff changeset	713 ``d == datetime.combine(d.date(), d.timetz())``. If date is a
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	714 :class:`.datetime` object, its time components and :attr:`tzinfo` attributes
71387 3935a1fb1db2 merge from 3.2 - Issue10403 - datetime module documentation changes based on review. Senthil Kumaran <senthil@uthcode.com> parents: 71212 diff changeset	715 are ignored.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	716
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	718 .. classmethod:: datetime.strptime(date_string, format)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	720 Return a :class:`.datetime` corresponding to date_string, parsed according to
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	721 format. This is equivalent to ``datetime(*(time.strptime(date_string,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	722 format)[0:6]))``. :exc:`ValueError` is raised if the date_string and format
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723 can't be parsed by :func:`time.strptime` or if it returns a value which isn't a
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	724 time tuple. See section :ref:`strftime-strptime-behavior`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	726 .. versionadded:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	728
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	729 Class attributes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731 .. attribute:: datetime.min
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	733 The earliest representable :class:`.datetime`, ``datetime(MINYEAR, 1, 1,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734 tzinfo=None)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	735
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	736
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737 .. attribute:: datetime.max
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	739 The latest representable :class:`.datetime`, ``datetime(MAXYEAR, 12, 31, 23, 59,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	740 59, 999999, tzinfo=None)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	741
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	742
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743 .. attribute:: datetime.resolution
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	745 The smallest possible difference between non-equal :class:`.datetime` objects,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746 ``timedelta(microseconds=1)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	748
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749 Instance attributes (read-only):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	750
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751 .. attribute:: datetime.year
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753 Between :const:`MINYEAR` and :const:`MAXYEAR` inclusive.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	755
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756 .. attribute:: datetime.month
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	757
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	758 Between 1 and 12 inclusive.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	759
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	760
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	761 .. attribute:: datetime.day
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	762
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	763 Between 1 and the number of days in the given month of the given year.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	764
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	766 .. attribute:: datetime.hour
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768 In ``range(24)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	770
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771 .. attribute:: datetime.minute
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773 In ``range(60)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	775
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	776 .. attribute:: datetime.second
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	778 In ``range(60)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	779
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	780
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	781 .. attribute:: datetime.microsecond
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	783 In ``range(1000000)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	785
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	786 .. attribute:: datetime.tzinfo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	788 The object passed as the tzinfo argument to the :class:`.datetime` constructor,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	789 or ``None`` if none was passed.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	790
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	791
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	792 Supported operations:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	793
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	794 +---------------------------------------+--------------------------------+
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	795 \| Operation \| Result \|
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	796 +=======================================+================================+
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	797 \| ``datetime2 = datetime1 + timedelta`` \| \(1) \|
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	798 +---------------------------------------+--------------------------------+
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	799 \| ``datetime2 = datetime1 - timedelta`` \| \(2) \|
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	800 +---------------------------------------+--------------------------------+
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	801 \| ``timedelta = datetime1 - datetime2`` \| \(3) \|
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	802 +---------------------------------------+--------------------------------+
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	803 \| ``datetime1 < datetime2`` \| Compares :class:`.datetime` to \|
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	804 \| \| :class:`.datetime`. (4) \|
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	805 +---------------------------------------+--------------------------------+
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	806
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	807 (1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	808 datetime2 is a duration of timedelta removed from datetime1, moving forward in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	809 time if ``timedelta.days`` > 0, or backward if ``timedelta.days`` < 0. The
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	810 result has the same :attr:`tzinfo` attribute as the input datetime, and
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	811 datetime2 - datetime1 == timedelta after. :exc:`OverflowError` is raised if
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	812 datetime2.year would be smaller than :const:`MINYEAR` or larger than
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	813 :const:`MAXYEAR`. Note that no time zone adjustments are done even if the
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	814 input is an aware object.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	815
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	816 (2)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	817 Computes the datetime2 such that datetime2 + timedelta == datetime1. As for
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	818 addition, the result has the same :attr:`tzinfo` attribute as the input
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	819 datetime, and no time zone adjustments are done even if the input is aware.
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	820 This isn't quite equivalent to datetime1 + (-timedelta), because -timedelta
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	821 in isolation can overflow in cases where datetime1 - timedelta does not.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	822
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	823 (3)
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	824 Subtraction of a :class:`.datetime` from a :class:`.datetime` is defined only if
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	825 both operands are naive, or if both are aware. If one is aware and the other is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	826 naive, :exc:`TypeError` is raised.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	827
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	828 If both are naive, or both are aware and have the same :attr:`tzinfo` attribute,
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	829 the :attr:`tzinfo` attributes are ignored, and the result is a :class:`timedelta`
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	830 object t such that ``datetime2 + t == datetime1``. No time zone adjustments
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	831 are done in this case.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	832
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	833 If both are aware and have different :attr:`tzinfo` attributes, ``a-b`` acts
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	834 as if a and b were first converted to naive UTC datetimes first. The
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	835 result is ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None)
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	836 - b.utcoffset())`` except that the implementation never overflows.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	837
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	838 (4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	839 datetime1 is considered less than datetime2 when datetime1 precedes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	840 datetime2 in time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	841
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	842 If one comparand is naive and the other is aware, :exc:`TypeError` is raised.
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	843 If both comparands are aware, and have the same :attr:`tzinfo` attribute, the
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	844 common :attr:`tzinfo` attribute is ignored and the base datetimes are
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	845 compared. If both comparands are aware and have different :attr:`tzinfo`
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	846 attributes, the comparands are first adjusted by subtracting their UTC
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	847 offsets (obtained from ``self.utcoffset()``).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	848
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	849 .. note::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	850
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	851 In order to stop comparison from falling back to the default scheme of comparing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	852 object addresses, datetime comparison normally raises :exc:`TypeError` if the
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	853 other comparand isn't also a :class:`.datetime` object. However,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	854 ``NotImplemented`` is returned instead if the other comparand has a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	855 :meth:`timetuple` attribute. This hook gives other kinds of date objects a
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	856 chance at implementing mixed-type comparison. If not, when a :class:`.datetime`
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	857 object is compared to an object of a different type, :exc:`TypeError` is raised
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	858 unless the comparison is ``==`` or ``!=``. The latter cases return
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	859 :const:`False` or :const:`True`, respectively.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	860
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	861 :class:`.datetime` objects can be used as dictionary keys. In Boolean contexts,
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	862 all :class:`.datetime` objects are considered to be true.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	863
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	864 Instance methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	865
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	866 .. method:: datetime.date()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	867
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	868 Return :class:`date` object with same year, month and day.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	869
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	870
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	871 .. method:: datetime.time()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	872
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	873 Return :class:`.time` object with same hour, minute, second and microsecond.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	874 :attr:`tzinfo` is ``None``. See also method :meth:`timetz`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	875
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	876
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	877 .. method:: datetime.timetz()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	878
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	879 Return :class:`.time` object with same hour, minute, second, microsecond, and
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	880 tzinfo attributes. See also method :meth:`time`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	881
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	882
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	883 .. method:: datetime.replace([year[, month[, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]]]]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	884
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	885 Return a datetime with the same attributes, except for those attributes given
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	886 new values by whichever keyword arguments are specified. Note that
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	887 ``tzinfo=None`` can be specified to create a naive datetime from an aware
71387 3935a1fb1db2 merge from 3.2 - Issue10403 - datetime module documentation changes based on review. Senthil Kumaran <senthil@uthcode.com> parents: 71212 diff changeset	888 datetime with no conversion of date and time data.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	889
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	890
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	891 .. method:: datetime.astimezone(tz)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	892
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	893 Return a :class:`.datetime` object with new :attr:`tzinfo` attribute tz,
71387 3935a1fb1db2 merge from 3.2 - Issue10403 - datetime module documentation changes based on review. Senthil Kumaran <senthil@uthcode.com> parents: 71212 diff changeset	894 adjusting the date and time data so the result is the same UTC time as
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	895 self, but in tz's local time.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	896
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	897 tz must be an instance of a :class:`tzinfo` subclass, and its
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	898 :meth:`utcoffset` and :meth:`dst` methods must not return ``None``. self must
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	899 be aware (``self.tzinfo`` must not be ``None``, and ``self.utcoffset()`` must
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	900 not return ``None``).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	901
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	902 If ``self.tzinfo`` is tz, ``self.astimezone(tz)`` is equal to self: no
71387 3935a1fb1db2 merge from 3.2 - Issue10403 - datetime module documentation changes based on review. Senthil Kumaran <senthil@uthcode.com> parents: 71212 diff changeset	903 adjustment of date or time data is performed. Else the result is local
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	904 time in time zone tz, representing the same UTC time as self: after
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	905 ``astz = dt.astimezone(tz)``, ``astz - astz.utcoffset()`` will usually have
71387 3935a1fb1db2 merge from 3.2 - Issue10403 - datetime module documentation changes based on review. Senthil Kumaran <senthil@uthcode.com> parents: 71212 diff changeset	906 the same date and time data as ``dt - dt.utcoffset()``. The discussion
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	907 of class :class:`tzinfo` explains the cases at Daylight Saving Time transition
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	908 boundaries where this cannot be achieved (an issue only if tz models both
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	909 standard and daylight time).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	910
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	911 If you merely want to attach a time zone object tz to a datetime dt without
71387 3935a1fb1db2 merge from 3.2 - Issue10403 - datetime module documentation changes based on review. Senthil Kumaran <senthil@uthcode.com> parents: 71212 diff changeset	912 adjustment of date and time data, use ``dt.replace(tzinfo=tz)``. If you
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	913 merely want to remove the time zone object from an aware datetime dt without
71387 3935a1fb1db2 merge from 3.2 - Issue10403 - datetime module documentation changes based on review. Senthil Kumaran <senthil@uthcode.com> parents: 71212 diff changeset	914 conversion of date and time data, use ``dt.replace(tzinfo=None)``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	915
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	916 Note that the default :meth:`tzinfo.fromutc` method can be overridden in a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	917 :class:`tzinfo` subclass to affect the result returned by :meth:`astimezone`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	918 Ignoring error cases, :meth:`astimezone` acts like::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	919
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	920 def astimezone(self, tz):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	921 if self.tzinfo is tz:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	922 return self
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	923 # Convert self to UTC, and attach the new time zone object.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	924 utc = (self - self.utcoffset()).replace(tzinfo=tz)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	925 # Convert from UTC to tz's local time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	926 return tz.fromutc(utc)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	927
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	928
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	929 .. method:: datetime.utcoffset()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	930
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	931 If :attr:`tzinfo` is ``None``, returns ``None``, else returns
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	932 ``self.tzinfo.utcoffset(self)``, and raises an exception if the latter doesn't
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	933 return ``None``, or a :class:`timedelta` object representing a whole number of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	934 minutes with magnitude less than one day.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	935
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	936
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	937 .. method:: datetime.dst()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	938
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	939 If :attr:`tzinfo` is ``None``, returns ``None``, else returns
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	940 ``self.tzinfo.dst(self)``, and raises an exception if the latter doesn't return
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	941 ``None``, or a :class:`timedelta` object representing a whole number of minutes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	942 with magnitude less than one day.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	943
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	944
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	945 .. method:: datetime.tzname()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	946
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	947 If :attr:`tzinfo` is ``None``, returns ``None``, else returns
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	948 ``self.tzinfo.tzname(self)``, raises an exception if the latter doesn't return
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	949 ``None`` or a string object,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	950
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	951
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	952 .. method:: datetime.timetuple()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	953
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	954 Return a :class:`time.struct_time` such as returned by :func:`time.localtime`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	955 ``d.timetuple()`` is equivalent to ``time.struct_time((d.year, d.month, d.day,
61876 21fa09f250e3 #1436346: make it more obvious that timetuple[7] is yday. Georg Brandl <georg@python.org> parents: 61454 diff changeset	956 d.hour, d.minute, d.second, d.weekday(), yday, dst))``, where ``yday =
21fa09f250e3 #1436346: make it more obvious that timetuple[7] is yday. Georg Brandl <georg@python.org> parents: 61454 diff changeset	957 d.toordinal() - date(d.year, 1, 1).toordinal() + 1`` is the day number within
21fa09f250e3 #1436346: make it more obvious that timetuple[7] is yday. Georg Brandl <georg@python.org> parents: 61454 diff changeset	958 the current year starting with ``1`` for January 1st. The :attr:`tm_isdst` flag
21fa09f250e3 #1436346: make it more obvious that timetuple[7] is yday. Georg Brandl <georg@python.org> parents: 61454 diff changeset	959 of the result is set according to the :meth:`dst` method: :attr:`tzinfo` is
65144 7018261f2ac1 Merged revisions 85274 via svnmerge from Georg Brandl <georg@python.org> parents: 63448 diff changeset	960 ``None`` or :meth:`dst` returns ``None``, :attr:`tm_isdst` is set to ``-1``;
61876 21fa09f250e3 #1436346: make it more obvious that timetuple[7] is yday. Georg Brandl <georg@python.org> parents: 61454 diff changeset	961 else if :meth:`dst` returns a non-zero value, :attr:`tm_isdst` is set to ``1``;
62212 329c129e07b6 Fixed markup of tm_isdst attribute. Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 61876 diff changeset	962 else :attr:`tm_isdst` is set to ``0``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	963
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	964
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	965 .. method:: datetime.utctimetuple()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	966
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	967 If :class:`.datetime` instance d is naive, this is the same as
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	968 ``d.timetuple()`` except that :attr:`tm_isdst` is forced to 0 regardless of what
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	969 ``d.dst()`` returns. DST is never in effect for a UTC time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	970
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	971 If d is aware, d is normalized to UTC time, by subtracting
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	972 ``d.utcoffset()``, and a :class:`time.struct_time` for the normalized time is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	973 returned. :attr:`tm_isdst` is forced to 0. Note that the result's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	974 :attr:`tm_year` member may be :const:`MINYEAR`\ -1 or :const:`MAXYEAR`\ +1, if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	975 d.year was ``MINYEAR`` or ``MAXYEAR`` and UTC adjustment spills over a year
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	976 boundary.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	977
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	978
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	979 .. method:: datetime.toordinal()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	980
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	981 Return the proleptic Gregorian ordinal of the date. The same as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	982 ``self.date().toordinal()``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	983
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	984
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	985 .. method:: datetime.weekday()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	986
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	987 Return the day of the week as an integer, where Monday is 0 and Sunday is 6.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	988 The same as ``self.date().weekday()``. See also :meth:`isoweekday`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	989
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	990
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	991 .. method:: datetime.isoweekday()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	992
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	993 Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	994 The same as ``self.date().isoweekday()``. See also :meth:`weekday`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	995 :meth:`isocalendar`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	996
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	997
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	998 .. method:: datetime.isocalendar()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	999
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1000 Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The same as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1001 ``self.date().isocalendar()``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1002
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1003
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1004 .. method:: datetime.isoformat([sep])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1005
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1006 Return a string representing the date and time in ISO 8601 format,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1007 YYYY-MM-DDTHH:MM:SS.mmmmmm or, if :attr:`microsecond` is 0,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1008 YYYY-MM-DDTHH:MM:SS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1009
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1010 If :meth:`utcoffset` does not return ``None``, a 6-character string is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1011 appended, giving the UTC offset in (signed) hours and minutes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1012 YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM or, if :attr:`microsecond` is 0
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1013 YYYY-MM-DDTHH:MM:SS+HH:MM
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1014
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1015 The optional argument sep (default ``'T'``) is a one-character separator,
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1016 placed between the date and time portions of the result. For example,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1017
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1018 >>> from datetime import tzinfo, timedelta, datetime
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1019 >>> class TZ(tzinfo):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1020 ... def utcoffset(self, dt): return timedelta(minutes=-399)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1021 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1022 >>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1023 '2002-12-25 00:00:00-06:39'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1024
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1025
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1026 .. method:: datetime.__str__()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1027
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1028 For a :class:`.datetime` instance d, ``str(d)`` is equivalent to
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1029 ``d.isoformat(' ')``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1030
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1031
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1032 .. method:: datetime.ctime()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1033
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1034 Return a string representing the date and time, for example ``datetime(2002, 12,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1035 4, 20, 30, 40).ctime() == 'Wed Dec 4 20:30:40 2002'``. ``d.ctime()`` is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1036 equivalent to ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 73269 diff changeset	1037 native C :c:func:`ctime` function (which :func:`time.ctime` invokes, but which
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1038 :meth:`datetime.ctime` does not invoke) conforms to the C standard.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1039
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1040
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1041 .. method:: datetime.strftime(format)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1042
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1043 Return a string representing the date and time, controlled by an explicit format
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1044 string. See section :ref:`strftime-strptime-behavior`.
9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1045
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1046
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1047 Examples of working with datetime objects:
f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1048
f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1049 .. doctest::
f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1050
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1051 >>> from datetime import datetime, date, time
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1052 >>> # Using datetime.combine()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1053 >>> d = date(2005, 7, 14)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1054 >>> t = time(12, 30)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1055 >>> datetime.combine(d, t)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1056 datetime.datetime(2005, 7, 14, 12, 30)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1057 >>> # Using datetime.now() or datetime.utcnow()
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1058 >>> datetime.now() # doctest: +SKIP
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1059 datetime.datetime(2007, 12, 6, 16, 29, 43, 79043) # GMT +1
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1060 >>> datetime.utcnow() # doctest: +SKIP
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1061 datetime.datetime(2007, 12, 6, 15, 29, 43, 79060)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1062 >>> # Using datetime.strptime()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1063 >>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1064 >>> dt
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1065 datetime.datetime(2006, 11, 21, 16, 30)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1066 >>> # Using datetime.timetuple() to get tuple of all attributes
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1067 >>> tt = dt.timetuple()
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1068 >>> for it in tt: # doctest: +SKIP
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1069 ... print it
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	1070 ...
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1071 2006 # year
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1072 11 # month
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1073 21 # day
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1074 16 # hour
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1075 30 # minute
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1076 0 # second
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1077 1 # weekday (0 = Monday)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1078 325 # number of days since 1st January
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1079 -1 # dst - method tzinfo.dst() returned None
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1080 >>> # Date in ISO format
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1081 >>> ic = dt.isocalendar()
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1082 >>> for it in ic: # doctest: +SKIP
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1083 ... print it
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1084 ...
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1085 2006 # ISO year
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1086 47 # ISO week
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1087 2 # ISO weekday
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1088 >>> # Formatting datetime
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1089 >>> dt.strftime("%A, %d. %B %Y %I:%M%p")
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1090 'Tuesday, 21. November 2006 04:30PM'
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1091
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1092 Using datetime with tzinfo:
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1093
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1094 >>> from datetime import timedelta, datetime, tzinfo
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1095 >>> class GMT1(tzinfo):
77806 01d180987d90 issue13666 - Fixing datetime documentation example when using tzinfo Senthil Kumaran <senthil@uthcode.com> parents: 76941 diff changeset	1096 ... def utcoffset(self, dt):
01d180987d90 issue13666 - Fixing datetime documentation example when using tzinfo Senthil Kumaran <senthil@uthcode.com> parents: 76941 diff changeset	1097 ... return timedelta(hours=1) + self.dst(dt)
01d180987d90 issue13666 - Fixing datetime documentation example when using tzinfo Senthil Kumaran <senthil@uthcode.com> parents: 76941 diff changeset	1098 ... def dst(self, dt):
01d180987d90 issue13666 - Fixing datetime documentation example when using tzinfo Senthil Kumaran <senthil@uthcode.com> parents: 76941 diff changeset	1099 ... # DST starts last Sunday in March
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1100 ... d = datetime(dt.year, 4, 1) # ends last Sunday in October
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1101 ... self.dston = d - timedelta(days=d.weekday() + 1)
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	1102 ... d = datetime(dt.year, 11, 1)
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1103 ... self.dstoff = d - timedelta(days=d.weekday() + 1)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1104 ... if self.dston <= dt.replace(tzinfo=None) < self.dstoff:
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1105 ... return timedelta(hours=1)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1106 ... else:
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1107 ... return timedelta(0)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1108 ... def tzname(self,dt):
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1109 ... return "GMT +1"
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	1110 ...
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1111 >>> class GMT2(tzinfo):
77806 01d180987d90 issue13666 - Fixing datetime documentation example when using tzinfo Senthil Kumaran <senthil@uthcode.com> parents: 76941 diff changeset	1112 ... def utcoffset(self, dt):
01d180987d90 issue13666 - Fixing datetime documentation example when using tzinfo Senthil Kumaran <senthil@uthcode.com> parents: 76941 diff changeset	1113 ... return timedelta(hours=2) + self.dst(dt)
01d180987d90 issue13666 - Fixing datetime documentation example when using tzinfo Senthil Kumaran <senthil@uthcode.com> parents: 76941 diff changeset	1114 ... def dst(self, dt):
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	1115 ... d = datetime(dt.year, 4, 1)
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1116 ... self.dston = d - timedelta(days=d.weekday() + 1)
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	1117 ... d = datetime(dt.year, 11, 1)
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1118 ... self.dstoff = d - timedelta(days=d.weekday() + 1)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1119 ... if self.dston <= dt.replace(tzinfo=None) < self.dstoff:
77806 01d180987d90 issue13666 - Fixing datetime documentation example when using tzinfo Senthil Kumaran <senthil@uthcode.com> parents: 76941 diff changeset	1120 ... return timedelta(hours=1)
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1121 ... else:
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1122 ... return timedelta(0)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1123 ... def tzname(self,dt):
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1124 ... return "GMT +2"
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	1125 ...
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1126 >>> gmt1 = GMT1()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1127 >>> # Daylight Saving Time
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1128 >>> dt1 = datetime(2006, 11, 21, 16, 30, tzinfo=gmt1)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1129 >>> dt1.dst()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1130 datetime.timedelta(0)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1131 >>> dt1.utcoffset()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1132 datetime.timedelta(0, 3600)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1133 >>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=gmt1)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1134 >>> dt2.dst()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1135 datetime.timedelta(0, 3600)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1136 >>> dt2.utcoffset()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1137 datetime.timedelta(0, 7200)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1138 >>> # Convert datetime to another time zone
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1139 >>> dt3 = dt2.astimezone(GMT2())
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1140 >>> dt3 # doctest: +ELLIPSIS
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1141 datetime.datetime(2006, 6, 14, 14, 0, tzinfo=<GMT2 object at 0x...>)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1142 >>> dt2 # doctest: +ELLIPSIS
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1143 datetime.datetime(2006, 6, 14, 13, 0, tzinfo=<GMT1 object at 0x...>)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1144 >>> dt2.utctimetuple() == dt3.utctimetuple()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1145 True
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	1146
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1147
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1148
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1149 .. _datetime-time:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1150
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1151 :class:`time` Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1152 ---------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1153
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1154 A time object represents a (local) time of day, independent of any particular
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1155 day, and subject to adjustment via a :class:`tzinfo` object.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1156
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1157 .. class:: time(hour[, minute[, second[, microsecond[, tzinfo]]]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1158
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1159 All arguments are optional. tzinfo may be ``None``, or an instance of a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1160 :class:`tzinfo` subclass. The remaining arguments may be ints or longs, in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1161 following ranges:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1162
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1163 * ``0 <= hour < 24``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1164 * ``0 <= minute < 60``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1165 * ``0 <= second < 60``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1166 * ``0 <= microsecond < 1000000``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1167
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1168 If an argument outside those ranges is given, :exc:`ValueError` is raised. All
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1169 default to ``0`` except tzinfo, which defaults to :const:`None`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1170
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1171 Class attributes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1172
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1173
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1174 .. attribute:: time.min
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1175
72580 854e31d80151 #13076: fix links to datetime.time. Ezio Melotti <ezio.melotti@gmail.com> parents: 71387 diff changeset	1176 The earliest representable :class:`.time`, ``time(0, 0, 0, 0)``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1177
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1178
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1179 .. attribute:: time.max
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1180
72580 854e31d80151 #13076: fix links to datetime.time. Ezio Melotti <ezio.melotti@gmail.com> parents: 71387 diff changeset	1181 The latest representable :class:`.time`, ``time(23, 59, 59, 999999)``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1182
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1183
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1184 .. attribute:: time.resolution
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1185
72580 854e31d80151 #13076: fix links to datetime.time. Ezio Melotti <ezio.melotti@gmail.com> parents: 71387 diff changeset	1186 The smallest possible difference between non-equal :class:`.time` objects,
854e31d80151 #13076: fix links to datetime.time. Ezio Melotti <ezio.melotti@gmail.com> parents: 71387 diff changeset	1187 ``timedelta(microseconds=1)``, although note that arithmetic on
854e31d80151 #13076: fix links to datetime.time. Ezio Melotti <ezio.melotti@gmail.com> parents: 71387 diff changeset	1188 :class:`.time` objects is not supported.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1189
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1190
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1191 Instance attributes (read-only):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1192
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1193 .. attribute:: time.hour
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1194
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1195 In ``range(24)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1196
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1197
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1198 .. attribute:: time.minute
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1199
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1200 In ``range(60)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1201
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1202
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1203 .. attribute:: time.second
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1204
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1205 In ``range(60)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1206
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1207
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1208 .. attribute:: time.microsecond
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1209
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1210 In ``range(1000000)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1211
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1212
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1213 .. attribute:: time.tzinfo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1214
72580 854e31d80151 #13076: fix links to datetime.time. Ezio Melotti <ezio.melotti@gmail.com> parents: 71387 diff changeset	1215 The object passed as the tzinfo argument to the :class:`.time` constructor, or
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1216 ``None`` if none was passed.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1217
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1218
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1219 Supported operations:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1220
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1221 * comparison of :class:`.time` to :class:`.time`, where a is considered less
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1222 than b when a precedes b in time. If one comparand is naive and the other
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1223 is aware, :exc:`TypeError` is raised. If both comparands are aware, and have
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	1224 the same :attr:`tzinfo` attribute, the common :attr:`tzinfo` attribute is
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	1225 ignored and the base times are compared. If both comparands are aware and
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	1226 have different :attr:`tzinfo` attributes, the comparands are first adjusted by
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	1227 subtracting their UTC offsets (obtained from ``self.utcoffset()``). In order
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	1228 to stop mixed-type comparisons from falling back to the default comparison by
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1229 object address, when a :class:`.time` object is compared to an object of a
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	1230 different type, :exc:`TypeError` is raised unless the comparison is ``==`` or
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	1231 ``!=``. The latter cases return :const:`False` or :const:`True`, respectively.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1232
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1233 * hash, use as dict key
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1234
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1235 * efficient pickling
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1236
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1237 * in Boolean contexts, a :class:`.time` object is considered to be true if and
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1238 only if, after converting it to minutes and subtracting :meth:`utcoffset` (or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1239 ``0`` if that's ``None``), the result is non-zero.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1240
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1241
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1242 Instance methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1243
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1244 .. method:: time.replace([hour[, minute[, second[, microsecond[, tzinfo]]]]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1245
72580 854e31d80151 #13076: fix links to datetime.time. Ezio Melotti <ezio.melotti@gmail.com> parents: 71387 diff changeset	1246 Return a :class:`.time` with the same value, except for those attributes given
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	1247 new values by whichever keyword arguments are specified. Note that
72580 854e31d80151 #13076: fix links to datetime.time. Ezio Melotti <ezio.melotti@gmail.com> parents: 71387 diff changeset	1248 ``tzinfo=None`` can be specified to create a naive :class:`.time` from an
854e31d80151 #13076: fix links to datetime.time. Ezio Melotti <ezio.melotti@gmail.com> parents: 71387 diff changeset	1249 aware :class:`.time`, without conversion of the time data.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1250
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1251
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1252 .. method:: time.isoformat()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1253
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1254 Return a string representing the time in ISO 8601 format, HH:MM:SS.mmmmmm or, if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1255 self.microsecond is 0, HH:MM:SS If :meth:`utcoffset` does not return ``None``, a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1256 6-character string is appended, giving the UTC offset in (signed) hours and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1257 minutes: HH:MM:SS.mmmmmm+HH:MM or, if self.microsecond is 0, HH:MM:SS+HH:MM
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1258
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1259
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1260 .. method:: time.__str__()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1261
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1262 For a time t, ``str(t)`` is equivalent to ``t.isoformat()``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1263
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1264
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1265 .. method:: time.strftime(format)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1266
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1267 Return a string representing the time, controlled by an explicit format string.
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1268 See section :ref:`strftime-strptime-behavior`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1269
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1270
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1271 .. method:: time.utcoffset()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1272
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1273 If :attr:`tzinfo` is ``None``, returns ``None``, else returns
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1274 ``self.tzinfo.utcoffset(None)``, and raises an exception if the latter doesn't
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1275 return ``None`` or a :class:`timedelta` object representing a whole number of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1276 minutes with magnitude less than one day.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1277
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1278
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1279 .. method:: time.dst()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1280
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1281 If :attr:`tzinfo` is ``None``, returns ``None``, else returns
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1282 ``self.tzinfo.dst(None)``, and raises an exception if the latter doesn't return
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1283 ``None``, or a :class:`timedelta` object representing a whole number of minutes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1284 with magnitude less than one day.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1285
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1286
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1287 .. method:: time.tzname()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1288
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1289 If :attr:`tzinfo` is ``None``, returns ``None``, else returns
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1290 ``self.tzinfo.tzname(None)``, or raises an exception if the latter doesn't
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1291 return ``None`` or a string object.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1292
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1293
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1294 Example:
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	1295
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1296 >>> from datetime import time, tzinfo
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1297 >>> class GMT1(tzinfo):
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1298 ... def utcoffset(self, dt):
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	1299 ... return timedelta(hours=1)
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	1300 ... def dst(self, dt):
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1301 ... return timedelta(0)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1302 ... def tzname(self,dt):
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1303 ... return "Europe/Prague"
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1304 ...
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1305 >>> t = time(12, 10, 30, tzinfo=GMT1())
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1306 >>> t # doctest: +ELLIPSIS
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1307 datetime.time(12, 10, 30, tzinfo=<GMT1 object at 0x...>)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1308 >>> gmt = GMT1()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1309 >>> t.isoformat()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1310 '12:10:30+01:00'
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1311 >>> t.dst()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1312 datetime.timedelta(0)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1313 >>> t.tzname()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1314 'Europe/Prague'
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1315 >>> t.strftime("%H:%M:%S %Z")
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1316 '12:10:30 Europe/Prague'
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1317
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1318
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1319 .. _datetime-tzinfo:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1320
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1321 :class:`tzinfo` Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1322 -----------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1323
51167 4abcf9d1b938 Merged revisions 69078-69079 via svnmerge from Brett Cannon <bcannon@gmail.com> parents: 50522 diff changeset	1324 :class:`tzinfo` is an abstract base class, meaning that this class should not be
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1325 instantiated directly. You need to derive a concrete subclass, and (at least)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1326 supply implementations of the standard :class:`tzinfo` methods needed by the
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1327 :class:`.datetime` methods you use. The :mod:`datetime` module does not supply
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1328 any concrete subclasses of :class:`tzinfo`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1329
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1330 An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1331 constructors for :class:`.datetime` and :class:`.time` objects. The latter objects
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	1332 view their attributes as being in local time, and the :class:`tzinfo` object
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1333 supports methods revealing offset of local time from UTC, the name of the time
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1334 zone, and DST offset, all relative to a date or time object passed to them.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1335
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1336 Special requirement for pickling: A :class:`tzinfo` subclass must have an
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1337 :meth:`__init__` method that can be called with no arguments, else it can be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1338 pickled but possibly not unpickled again. This is a technical requirement that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1339 may be relaxed in the future.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1340
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1341 A concrete subclass of :class:`tzinfo` may need to implement the following
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1342 methods. Exactly which methods are needed depends on the uses made of aware
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1343 :mod:`datetime` objects. If in doubt, simply implement all of them.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1344
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1345
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1346 .. method:: tzinfo.utcoffset(self, dt)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1347
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1348 Return offset of local time from UTC, in minutes east of UTC. If local time is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1349 west of UTC, this should be negative. Note that this is intended to be the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1350 total offset from UTC; for example, if a :class:`tzinfo` object represents both
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1351 time zone and DST adjustments, :meth:`utcoffset` should return their sum. If
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1352 the UTC offset isn't known, return ``None``. Else the value returned must be a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1353 :class:`timedelta` object specifying a whole number of minutes in the range
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1354 -1439 to 1439 inclusive (1440 = 24\*60; the magnitude of the offset must be less
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1355 than one day). Most implementations of :meth:`utcoffset` will probably look
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1356 like one of these two::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1357
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1358 return CONSTANT # fixed-offset class
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1359 return CONSTANT + self.dst(dt) # daylight-aware class
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1360
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1361 If :meth:`utcoffset` does not return ``None``, :meth:`dst` should not return
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1362 ``None`` either.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1363
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1364 The default implementation of :meth:`utcoffset` raises
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1365 :exc:`NotImplementedError`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1366
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1367
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1368 .. method:: tzinfo.dst(self, dt)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1369
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1370 Return the daylight saving time (DST) adjustment, in minutes east of UTC, or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1371 ``None`` if DST information isn't known. Return ``timedelta(0)`` if DST is not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1372 in effect. If DST is in effect, return the offset as a :class:`timedelta` object
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1373 (see :meth:`utcoffset` for details). Note that DST offset, if applicable, has
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1374 already been added to the UTC offset returned by :meth:`utcoffset`, so there's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1375 no need to consult :meth:`dst` unless you're interested in obtaining DST info
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1376 separately. For example, :meth:`datetime.timetuple` calls its :attr:`tzinfo`
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	1377 attribute's :meth:`dst` method to determine how the :attr:`tm_isdst` flag
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	1378 should be set, and :meth:`tzinfo.fromutc` calls :meth:`dst` to account for
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	1379 DST changes when crossing time zones.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1380
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1381 An instance tz of a :class:`tzinfo` subclass that models both standard and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1382 daylight times must be consistent in this sense:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1383
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1384 ``tz.utcoffset(dt) - tz.dst(dt)``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1385
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1386 must return the same result for every :class:`.datetime` dt with ``dt.tzinfo ==
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1387 tz`` For sane :class:`tzinfo` subclasses, this expression yields the time
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1388 zone's "standard offset", which should not depend on the date or the time, but
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1389 only on geographic location. The implementation of :meth:`datetime.astimezone`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1390 relies on this, but cannot detect violations; it's the programmer's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1391 responsibility to ensure it. If a :class:`tzinfo` subclass cannot guarantee
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1392 this, it may be able to override the default implementation of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1393 :meth:`tzinfo.fromutc` to work correctly with :meth:`astimezone` regardless.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1394
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1395 Most implementations of :meth:`dst` will probably look like one of these two::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1396
73269 a38dd36a44fa correct signature for tzinfo.dst() in examples; thanks to Daniil Shved from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 72580 diff changeset	1397 def dst(self, dt):
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1398 # a fixed-offset class: doesn't account for DST
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1399 return timedelta(0)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1400
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1401 or ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1402
73269 a38dd36a44fa correct signature for tzinfo.dst() in examples; thanks to Daniil Shved from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 72580 diff changeset	1403 def dst(self, dt):
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1404 # Code to set dston and dstoff to the time zone's DST
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1405 # transition times based on the input dt.year, and expressed
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1406 # in standard local time. Then
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1407
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1408 if dston <= dt.replace(tzinfo=None) < dstoff:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1409 return timedelta(hours=1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1410 else:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1411 return timedelta(0)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1412
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1413 The default implementation of :meth:`dst` raises :exc:`NotImplementedError`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1414
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1415
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1416 .. method:: tzinfo.tzname(self, dt)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1417
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1418 Return the time zone name corresponding to the :class:`.datetime` object dt, as
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1419 a string. Nothing about string names is defined by the :mod:`datetime` module,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1420 and there's no requirement that it mean anything in particular. For example,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1421 "GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" are all
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1422 valid replies. Return ``None`` if a string name isn't known. Note that this is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1423 a method rather than a fixed string primarily because some :class:`tzinfo`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1424 subclasses will wish to return different names depending on the specific value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1425 of dt passed, especially if the :class:`tzinfo` class is accounting for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1426 daylight time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1427
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1428 The default implementation of :meth:`tzname` raises :exc:`NotImplementedError`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1429
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1430
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1431 These methods are called by a :class:`.datetime` or :class:`.time` object, in
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1432 response to their methods of the same names. A :class:`.datetime` object passes
30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1433 itself as the argument, and a :class:`.time` object passes ``None`` as the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1434 argument. A :class:`tzinfo` subclass's methods should therefore be prepared to
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1435 accept a dt argument of ``None``, or of class :class:`.datetime`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1436
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1437 When ``None`` is passed, it's up to the class designer to decide the best
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1438 response. For example, returning ``None`` is appropriate if the class wishes to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1439 say that time objects don't participate in the :class:`tzinfo` protocols. It
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1440 may be more useful for ``utcoffset(None)`` to return the standard UTC offset, as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1441 there is no other convention for discovering the standard offset.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1442
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1443 When a :class:`.datetime` object is passed in response to a :class:`.datetime`
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1444 method, ``dt.tzinfo`` is the same object as self. :class:`tzinfo` methods can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1445 rely on this, unless user code calls :class:`tzinfo` methods directly. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1446 intent is that the :class:`tzinfo` methods interpret dt as being in local
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1447 time, and not need worry about objects in other timezones.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1448
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1449 There is one more :class:`tzinfo` method that a subclass may wish to override:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1450
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1451
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1452 .. method:: tzinfo.fromutc(self, dt)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1453
71387 3935a1fb1db2 merge from 3.2 - Issue10403 - datetime module documentation changes based on review. Senthil Kumaran <senthil@uthcode.com> parents: 71212 diff changeset	1454 This is called from the default :class:`datetime.astimezone()`
3935a1fb1db2 merge from 3.2 - Issue10403 - datetime module documentation changes based on review. Senthil Kumaran <senthil@uthcode.com> parents: 71212 diff changeset	1455 implementation. When called from that, ``dt.tzinfo`` is self, and dt's
3935a1fb1db2 merge from 3.2 - Issue10403 - datetime module documentation changes based on review. Senthil Kumaran <senthil@uthcode.com> parents: 71212 diff changeset	1456 date and time data are to be viewed as expressing a UTC time. The purpose
3935a1fb1db2 merge from 3.2 - Issue10403 - datetime module documentation changes based on review. Senthil Kumaran <senthil@uthcode.com> parents: 71212 diff changeset	1457 of :meth:`fromutc` is to adjust the date and time data, returning an
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	1458 equivalent datetime in self's local time.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1459
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1460 Most :class:`tzinfo` subclasses should be able to inherit the default
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1461 :meth:`fromutc` implementation without problems. It's strong enough to handle
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1462 fixed-offset time zones, and time zones accounting for both standard and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1463 daylight time, and the latter even if the DST transition times differ in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1464 different years. An example of a time zone the default :meth:`fromutc`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1465 implementation may not handle correctly in all cases is one where the standard
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1466 offset (from UTC) depends on the specific date and time passed, which can happen
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1467 for political reasons. The default implementations of :meth:`astimezone` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1468 :meth:`fromutc` may not produce the result you want if the result is one of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1469 hours straddling the moment the standard offset changes.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1470
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1471 Skipping code for error cases, the default :meth:`fromutc` implementation acts
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1472 like::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1473
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1474 def fromutc(self, dt):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1475 # raise ValueError error if dt.tzinfo is not self
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1476 dtoff = dt.utcoffset()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1477 dtdst = dt.dst()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1478 # raise ValueError if dtoff is None or dtdst is None
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1479 delta = dtoff - dtdst # this is self's standard offset
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1480 if delta:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1481 dt += delta # convert to standard local time
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1482 dtdst = dt.dst()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1483 # raise ValueError if dtdst is None
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1484 if dtdst:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1485 return dt + dtdst
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1486 else:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1487 return dt
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1488
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1489 Example :class:`tzinfo` classes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1490
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1491 .. literalinclude:: ../includes/tzinfo-examples.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1492
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1493
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1494 Note that there are unavoidable subtleties twice per year in a :class:`tzinfo`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1495 subclass accounting for both standard and daylight time, at the DST transition
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1496 points. For concreteness, consider US Eastern (UTC -0500), where EDT begins the
59845 f96c8293dd7f Merged revisions 78859-78860,78952,79168-79169,79173,79176,79178-79179,79181,79184-79185,79192,79212 via svnmerge from Georg Brandl <georg@python.org> parents: 59834 diff changeset	1497 minute after 1:59 (EST) on the second Sunday in March, and ends the minute after
f96c8293dd7f Merged revisions 78859-78860,78952,79168-79169,79173,79176,79178-79179,79181,79184-79185,79192,79212 via svnmerge from Georg Brandl <georg@python.org> parents: 59834 diff changeset	1498 1:59 (EDT) on the first Sunday in November::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1499
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1500 UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1501 EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1502 EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1503
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1504 start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1505
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1506 end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1507
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1508 When DST starts (the "start" line), the local wall clock leaps from 1:59 to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1509 3:00. A wall time of the form 2:MM doesn't really make sense on that day, so
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1510 ``astimezone(Eastern)`` won't deliver a result with ``hour == 2`` on the day DST
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1511 begins. In order for :meth:`astimezone` to make this guarantee, the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1512 :meth:`rzinfo.dst` method must consider times in the "missing hour" (2:MM for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1513 Eastern) to be in daylight time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1514
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1515 When DST ends (the "end" line), there's a potentially worse problem: there's an
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1516 hour that can't be spelled unambiguously in local wall time: the last hour of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1517 daylight time. In Eastern, that's times of the form 5:MM UTC on the day
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1518 daylight time ends. The local wall clock leaps from 1:59 (daylight time) back
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1519 to 1:00 (standard time) again. Local times of the form 1:MM are ambiguous.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1520 :meth:`astimezone` mimics the local clock's behavior by mapping two adjacent UTC
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1521 hours into the same local hour then. In the Eastern example, UTC times of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1522 form 5:MM and 6:MM both map to 1:MM when converted to Eastern. In order for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1523 :meth:`astimezone` to make this guarantee, the :meth:`tzinfo.dst` method must
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1524 consider times in the "repeated hour" to be in standard time. This is easily
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1525 arranged, as in the example, by expressing DST switch times in the time zone's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1526 standard local time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1527
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1528 Applications that can't bear such ambiguities should avoid using hybrid
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1529 :class:`tzinfo` subclasses; there are no ambiguities when using UTC, or any
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1530 other fixed-offset :class:`tzinfo` subclass (such as a class representing only
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1531 EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	1532
76532 e0e421133d0f Issue #14448: mention pytz; patch by Andrew Svetlov Sandro Tosi <sandro.tosi@gmail.com> parents: 75021 diff changeset	1533 .. seealso::
e0e421133d0f Issue #14448: mention pytz; patch by Andrew Svetlov Sandro Tosi <sandro.tosi@gmail.com> parents: 75021 diff changeset	1534
e0e421133d0f Issue #14448: mention pytz; patch by Andrew Svetlov Sandro Tosi <sandro.tosi@gmail.com> parents: 75021 diff changeset	1535 `pytz <http://pypi.python.org/pypi/pytz/>`_
76591 1e5a483248ce Issue #14448: add reference to IANA timezone database; thanks to Georg/Nick suggestions Sandro Tosi <sandro.tosi@gmail.com> parents: 76532 diff changeset	1536 The standard library has no :class:`tzinfo` instances except for UTC, but
1e5a483248ce Issue #14448: add reference to IANA timezone database; thanks to Georg/Nick suggestions Sandro Tosi <sandro.tosi@gmail.com> parents: 76532 diff changeset	1537 there exists a third-party library which brings the *IANA timezone
1e5a483248ce Issue #14448: add reference to IANA timezone database; thanks to Georg/Nick suggestions Sandro Tosi <sandro.tosi@gmail.com> parents: 76532 diff changeset	1538 database* (also known as the Olson database) to Python: pytz.
1e5a483248ce Issue #14448: add reference to IANA timezone database; thanks to Georg/Nick suggestions Sandro Tosi <sandro.tosi@gmail.com> parents: 76532 diff changeset	1539
1e5a483248ce Issue #14448: add reference to IANA timezone database; thanks to Georg/Nick suggestions Sandro Tosi <sandro.tosi@gmail.com> parents: 76532 diff changeset	1540 pytz contains up-to-date information and its usage is recommended.
76532 e0e421133d0f Issue #14448: mention pytz; patch by Andrew Svetlov Sandro Tosi <sandro.tosi@gmail.com> parents: 75021 diff changeset	1541
76591 1e5a483248ce Issue #14448: add reference to IANA timezone database; thanks to Georg/Nick suggestions Sandro Tosi <sandro.tosi@gmail.com> parents: 76532 diff changeset	1542 `IANA timezone database <http://www.iana.org/time-zones>`_
1e5a483248ce Issue #14448: add reference to IANA timezone database; thanks to Georg/Nick suggestions Sandro Tosi <sandro.tosi@gmail.com> parents: 76532 diff changeset	1543 The Time Zone Database (often called tz or zoneinfo) contains code and
1e5a483248ce Issue #14448: add reference to IANA timezone database; thanks to Georg/Nick suggestions Sandro Tosi <sandro.tosi@gmail.com> parents: 76532 diff changeset	1544 data that represent the history of local time for many representative
1e5a483248ce Issue #14448: add reference to IANA timezone database; thanks to Georg/Nick suggestions Sandro Tosi <sandro.tosi@gmail.com> parents: 76532 diff changeset	1545 locations around the globe. It is updated periodically to reflect changes
1e5a483248ce Issue #14448: add reference to IANA timezone database; thanks to Georg/Nick suggestions Sandro Tosi <sandro.tosi@gmail.com> parents: 76532 diff changeset	1546 made by political bodies to time zone boundaries, UTC offsets, and
1e5a483248ce Issue #14448: add reference to IANA timezone database; thanks to Georg/Nick suggestions Sandro Tosi <sandro.tosi@gmail.com> parents: 76532 diff changeset	1547 daylight-saving rules.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1548
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1549 .. _strftime-strptime-behavior:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1550
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1551 :meth:`strftime` and :meth:`strptime` Behavior
9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1552 ----------------------------------------------
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1553
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1554 :class:`date`, :class:`.datetime`, and :class:`.time` objects all support a
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1555 ``strftime(format)`` method, to create a string representing the time under the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1556 control of an explicit format string. Broadly speaking, ``d.strftime(fmt)``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1557 acts like the :mod:`time` module's ``time.strftime(fmt, d.timetuple())``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1558 although not all objects support a :meth:`timetuple` method.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1559
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1560 Conversely, the :meth:`datetime.strptime` class method creates a
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1561 :class:`.datetime` object from a string representing a date and time and a
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1562 corresponding format string. ``datetime.strptime(date_string, format)`` is
9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1563 equivalent to ``datetime(*(time.strptime(date_string, format)[0:6]))``.
9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1564
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1565 For :class:`.time` objects, the format codes for year, month, and day should not
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1566 be used, as time objects have no such values. If they're used anyway, ``1900``
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1567 is substituted for the year, and ``1`` for the month and day.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1568
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1569 For :class:`date` objects, the format codes for hours, minutes, seconds, and
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1570 microseconds should not be used, as :class:`date` objects have no such
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1571 values. If they're used anyway, ``0`` is substituted for them.
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1572
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1573 .. versionadded:: 2.6
75021 30ff707ed75f Refer to 'time' and 'datetime' submodules; thanks to Erik Johnson from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74395 diff changeset	1574 :class:`.time` and :class:`.datetime` objects support a ``%f`` format code
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 51167 diff changeset	1575 which expands to the number of microseconds in the object, zero-padded on
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 51167 diff changeset	1576 the left to six places.
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1577
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1578 For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1579 strings.
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1580
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1581 For an aware object:
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1582
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1583 ``%z``
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1584 :meth:`utcoffset` is transformed into a 5-character string of the form +HHMM or
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1585 -HHMM, where HH is a 2-digit string giving the number of UTC offset hours, and
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1586 MM is a 2-digit string giving the number of UTC offset minutes. For example, if
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1587 :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1588 replaced with the string ``'-0330'``.
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1589
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1590 ``%Z``
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1591 If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty string.
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1592 Otherwise ``%Z`` is replaced by the returned value, which must be a string.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1593
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1594 The full set of format codes supported varies across platforms, because Python
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1595 calls the platform C library's :func:`strftime` function, and platform
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46011 diff changeset	1596 variations are common.
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1597
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1598 The following is a list of all the format codes that the C standard (1989
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1599 version) requires, and these work on all platforms with a standard C
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1600 implementation. Note that the 1999 version of the C standard added additional
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1601 format codes.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1602
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1603 The exact range of years for which :meth:`strftime` works also varies across
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1604 platforms. Regardless of platform, years before 1900 cannot be used.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1605
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1606 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1607 \| Directive \| Meaning \| Notes \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1608 +===========+================================+=======+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1609 \| ``%a`` \| Locale's abbreviated weekday \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1610 \| \| name. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1611 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1612 \| ``%A`` \| Locale's full weekday name. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1613 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1614 \| ``%b`` \| Locale's abbreviated month \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1615 \| \| name. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1616 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1617 \| ``%B`` \| Locale's full month name. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1618 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1619 \| ``%c`` \| Locale's appropriate date and \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1620 \| \| time representation. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1621 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1622 \| ``%d`` \| Day of the month as a decimal \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1623 \| \| number [01,31]. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1624 +-----------+--------------------------------+-------+
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1625 \| ``%f`` \| Microsecond as a decimal \| \(1) \|
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1626 \| \| number [0,999999], zero-padded \| \|
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1627 \| \| on the left \| \|
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1628 +-----------+--------------------------------+-------+
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1629 \| ``%H`` \| Hour (24-hour clock) as a \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1630 \| \| decimal number [00,23]. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1631 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1632 \| ``%I`` \| Hour (12-hour clock) as a \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1633 \| \| decimal number [01,12]. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1634 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1635 \| ``%j`` \| Day of the year as a decimal \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1636 \| \| number [001,366]. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1637 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1638 \| ``%m`` \| Month as a decimal number \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1639 \| \| [01,12]. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1640 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1641 \| ``%M`` \| Minute as a decimal number \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1642 \| \| [00,59]. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1643 +-----------+--------------------------------+-------+
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1644 \| ``%p`` \| Locale's equivalent of either \| \(2) \|
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1645 \| \| AM or PM. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1646 +-----------+--------------------------------+-------+
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1647 \| ``%S`` \| Second as a decimal number \| \(3) \|
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1648 \| \| [00,61]. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1649 +-----------+--------------------------------+-------+
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1650 \| ``%U`` \| Week number of the year \| \(4) \|
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1651 \| \| (Sunday as the first day of \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1652 \| \| the week) as a decimal number \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1653 \| \| [00,53]. All days in a new \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1654 \| \| year preceding the first \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1655 \| \| Sunday are considered to be in \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1656 \| \| week 0. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1657 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1658 \| ``%w`` \| Weekday as a decimal number \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1659 \| \| [0(Sunday),6]. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1660 +-----------+--------------------------------+-------+
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1661 \| ``%W`` \| Week number of the year \| \(4) \|
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1662 \| \| (Monday as the first day of \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1663 \| \| the week) as a decimal number \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1664 \| \| [00,53]. All days in a new \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1665 \| \| year preceding the first \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1666 \| \| Monday are considered to be in \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1667 \| \| week 0. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1668 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1669 \| ``%x`` \| Locale's appropriate date \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1670 \| \| representation. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1671 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1672 \| ``%X`` \| Locale's appropriate time \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1673 \| \| representation. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1674 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1675 \| ``%y`` \| Year without century as a \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1676 \| \| decimal number [00,99]. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1677 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1678 \| ``%Y`` \| Year with century as a decimal \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1679 \| \| number. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1680 +-----------+--------------------------------+-------+
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1681 \| ``%z`` \| UTC offset in the form +HHMM \| \(5) \|
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1682 \| \| or -HHMM (empty string if the \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1683 \| \| the object is naive). \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1684 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1685 \| ``%Z`` \| Time zone name (empty string \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1686 \| \| if the object is naive). \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1687 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1688 \| ``%%`` \| A literal ``'%'`` character. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1689 +-----------+--------------------------------+-------+
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1690
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1691 Notes:
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1692
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1693 (1)
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1694 When used with the :meth:`strptime` method, the ``%f`` directive
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1695 accepts from one to six digits and zero pads on the right. ``%f`` is
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 51167 diff changeset	1696 an extension to the set of format characters in the C standard (but
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 51167 diff changeset	1697 implemented separately in datetime objects, and therefore always
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 51167 diff changeset	1698 available).
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1699
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1700 (2)
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1701 When used with the :meth:`strptime` method, the ``%p`` directive only affects
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1702 the output hour field if the ``%I`` directive is used to parse the hour.
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1703
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1704 (3)
52725 fcbe1ad24d41 Merged revisions 71037 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 51809 diff changeset	1705 The range really is ``0`` to ``61``; according to the Posix standard this
fcbe1ad24d41 Merged revisions 71037 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 51809 diff changeset	1706 accounts for leap seconds and the (very rare) double leap seconds.
fcbe1ad24d41 Merged revisions 71037 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 51809 diff changeset	1707 The :mod:`time` module may produce and does accept leap seconds since
fcbe1ad24d41 Merged revisions 71037 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 51809 diff changeset	1708 it is based on the Posix standard, but the :mod:`datetime` module
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1709 does not accept leap seconds in :meth:`strptime` input nor will it
52725 fcbe1ad24d41 Merged revisions 71037 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 51809 diff changeset	1710 produce them in :func:`strftime` output.
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1711
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1712 (4)
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 57092 diff changeset	1713 When used with the :meth:`strptime` method, ``%U`` and ``%W`` are only used in
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1714 calculations when the day of the week and the year are specified.
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1715
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1716 (5)
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1717 For example, if :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``,
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1718 ``%z`` is replaced with the string ``'-0330'``.
76940 5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	1719
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	1720
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	1721 .. rubric:: Footnotes
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	1722
5d1b32e33e67 #14766: Add correct algorithm for when a 'time' object is naive. R David Murray <rdmurray@bitdance.com> parents: 76591 diff changeset	1723 .. [#] If, that is, we ignore the effects of Relativity

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/datetime.rst @ 79675:c0a2294de787 2.7