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

annotate Doc/library/datetime.rst @ 54294:dba767bc3155 legacy-trunk

remove mention of old ctypes version

author	Benjamin Peterson <benjamin@python.org>
date	Sat, 23 May 2009 20:59:09 +0000
parents	8d84f220ff27
children	a09da56e4796

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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 focus of the implementation is on efficient member extraction for output
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 formatting and manipulation. For related
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 functionality, see also the :mod:`time` and :mod:`calendar` modules.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 There are two kinds of date and time objects: "naive" and "aware". This
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 distinction refers to whether the object has any notion of time zone, daylight
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 saving time, or other kind of algorithmic or political time adjustment. Whether
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 a naive :class:`datetime` object represents Coordinated Universal Time (UTC),
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 local time, or time in some other timezone is purely up to the program, just
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 like it's up to the program whether a particular number represents metres,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 miles, or mass. Naive :class:`datetime` objects are easy to understand and to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 work with, at the cost of ignoring some aspects of reality.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 For applications requiring more, :class:`datetime` and :class:`time` objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 have an optional time zone information member, :attr:`tzinfo`, that can contain
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 an instance of a subclass of the abstract :class:`tzinfo` class. These
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 :class:`tzinfo` objects capture information about the offset from UTC time, the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33 time zone name, and whether Daylight Saving Time is in effect. Note that no
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 concrete :class:`tzinfo` classes are supplied by the :mod:`datetime` module.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 Supporting timezones at whatever level of detail is required is up to the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 application. The rules for time adjustment across the world are more political
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37 than rational, and there is no standard suitable for every application.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 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	40
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 .. data:: MINYEAR
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44 The smallest year number allowed in a :class:`date` or :class:`datetime` object.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 :const:`MINYEAR` is ``1``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46
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:: MAXYEAR
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 The largest year number allowed in a :class:`date` or :class:`datetime` object.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 :const:`MAXYEAR` is ``9999``.
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 .. seealso::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56 Module :mod:`calendar`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57 General calendar related functions.
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 Module :mod:`time`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 Time access and conversions.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 Available Types
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 .. class:: date
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 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	70 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	71 :attr:`day`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74 .. class:: time
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 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	77 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	78 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	79 and :attr:`tzinfo`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 .. class:: datetime
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 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	85 :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	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:: timedelta
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 A duration expressing the difference between two :class:`date`, :class:`time`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 or :class:`datetime` instances to microsecond resolution.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 .. class:: tzinfo
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 An abstract base class for time zone information objects. These are used by the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 :class:`datetime` and :class:`time` classes to provide a customizable notion of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 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	100 time).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 Objects of these types are immutable.
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 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	105
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 An object d of type :class:`time` or :class:`datetime` may be naive or aware.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107 d is aware if ``d.tzinfo`` is not ``None`` and ``d.tzinfo.utcoffset(d)`` does
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 not return ``None``. If ``d.tzinfo`` is ``None``, or if ``d.tzinfo`` is not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 ``None`` but ``d.tzinfo.utcoffset(d)`` returns ``None``, d is naive.
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 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	112 objects.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 Subclass relationships::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116 object
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 timedelta
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 tzinfo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119 time
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120 date
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 datetime
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 .. _datetime-timedelta:
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 :class:`timedelta` Objects
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129 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	130 dates or times.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 .. 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	134
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 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	136 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	137
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 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	139 converted to those units:
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 millisecond is converted to 1000 microseconds.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 * A minute is converted to 60 seconds.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 * An hour is converted to 3600 seconds.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 * A week is converted to 7 days.
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 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	147 representation is unique, with
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 * ``0 <= microseconds < 1000000``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 * ``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	151 * ``-999999999 <= days <= 999999999``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 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	154 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	155 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	156 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	157
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158 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	159 :exc:`OverflowError` is raised.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 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	162 example,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	164 >>> from datetime import timedelta
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165 >>> d = timedelta(microseconds=-1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166 >>> (d.days, d.seconds, d.microseconds)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 (-1, 86399, 999999)
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 Class attributes are:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170
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 .. attribute:: timedelta.min
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174 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	175
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177 .. attribute:: timedelta.max
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179 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	180 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	181
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.resolution
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 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	186 ``timedelta(microseconds=1)``.
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 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	189 ``-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	190
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191 Instance attributes (read-only):
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 \| Value \|
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 \| ``days`` \| Between -999999999 and 999999999 inclusive \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 +------------------+--------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198 \| ``seconds`` \| Between 0 and 86399 inclusive \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 +------------------+--------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 \| ``microseconds`` \| Between 0 and 999999 inclusive \|
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 Supported operations:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44221 diff changeset	205 .. XXX this table is too wide!
42604 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 +--------------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 \| Operation \| Result \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 +================================+===============================================+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 \| ``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	211 \| \| 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	212 +--------------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213 \| ``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	214 \| \| == t2 - t3 and t2 == t1 + t3 are \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215 \| \| true. (1) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216 +--------------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217 \| ``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	218 \| \| Afterwards t1 // i == t2 is true, \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 \| \| provided ``i != 0``. \|
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 \| \| 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	222 \| \| is 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 // 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	225 \| \| any) is thrown away. (3) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 +--------------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227 \| ``+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	228 \| \| same value. (2) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 +--------------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 \| ``-t1`` \| equivalent to :class:`timedelta`\ \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 \| \| (-t1.days, -t1.seconds, \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232 \| \| -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	233 +--------------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 \| ``abs(t)`` \| equivalent to +t when ``t.days >= 0``, and \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 \| \| to -t when ``t.days < 0``. (2) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 +--------------------------------+-----------------------------------------------+
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 Notes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 (1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 This is exact, but may overflow.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 (2)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 This is exact, and cannot overflow.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 (3)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 Division by 0 raises :exc:`ZeroDivisionError`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 (4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 -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	251
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252 In addition to the operations listed above :class:`timedelta` objects support
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253 certain additions and subtractions with :class:`date` and :class:`datetime`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254 objects (see below).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 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	257 :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	258 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	259 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	260 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	261 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	262 :const:`True`, respectively.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263
43753 4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 42604 diff changeset	264 :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	265 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	266 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	267
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	268 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	269
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	270 >>> 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	271 >>> 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	272 >>> 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	273 ... minutes=50, seconds=600) # adds up to 365 days
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	274 >>> 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	275 True
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	276 >>> 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	277 >>> 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	278 (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	279 >>> 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	280 >>> 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	281 (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	282 >>> 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	283 >>> 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	284 (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	285 >>> 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	286 True
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	287
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 .. _datetime-date:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291 :class:`date` Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292 ---------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 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	295 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	296 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	297 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	298 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	299 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	300 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	301 systems.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304 .. class:: date(year, month, day)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306 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	307 ranges:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309 * ``MINYEAR <= year <= MAXYEAR``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 * ``1 <= month <= 12``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311 * ``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	312
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313 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	314
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315 Other constructors, all class methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 .. method:: date.today()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320 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	321 ``date.fromtimestamp(time.time())``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 .. method:: date.fromtimestamp(timestamp)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 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	327 by :func:`time.time`. This may raise :exc:`ValueError`, if the timestamp is out
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 of the range of values supported by the platform C :cfunc:`localtime` function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 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	330 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	331 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	332
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 .. method:: date.fromordinal(ordinal)
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 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	337 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	338 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	339 d``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341 Class attributes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 .. attribute:: date.min
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346 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	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 .. attribute:: date.max
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 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	352
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 .. attribute:: date.resolution
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 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	357 ``timedelta(days=1)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359 Instance attributes (read-only):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362 .. attribute:: date.year
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364 Between :const:`MINYEAR` and :const:`MAXYEAR` inclusive.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367 .. attribute:: date.month
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369 Between 1 and 12 inclusive.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372 .. attribute:: date.day
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374 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	375
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376 Supported operations:
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 +-------------------------------+----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379 \| Operation \| Result \|
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 \| ``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	382 \| \| from date1. (1) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383 +-------------------------------+----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384 \| ``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	385 \| \| timedelta == date1``. (2) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386 +-------------------------------+----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387 \| ``timedelta = date1 - date2`` \| \(3) \|
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 \| ``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	390 \| \| date1 precedes date2 in time. (4) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391 +-------------------------------+----------------------------------------------+
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 Notes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395 (1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396 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	397 ``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	398 ``timedelta.seconds`` and ``timedelta.microseconds`` are ignored.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399 :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	400 :const:`MINYEAR` or larger than :const:`MAXYEAR`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 (2)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403 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	404 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	405 ``timedelta.seconds`` and ``timedelta.microseconds`` are ignored.
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 (3)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 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	409 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	410
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 (4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412 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	413 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	414 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	415 :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	416 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	417 :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	418 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	419 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	420 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	421 :const:`False` or :const:`True`, respectively.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423 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	424 objects are considered to be true.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 Instance methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429 .. method:: date.replace(year, month, day)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431 Return a date with the same value, except for those members given new values by
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432 whichever keyword arguments are specified. For example, if ``d == date(2002,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433 12, 31)``, then ``d.replace(day=26) == date(2002, 12, 26)``.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	436 .. method:: date.timetuple()
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 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	439 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	440 is equivalent to ``time.struct_time((d.year, d.month, d.day, 0, 0, 0,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 d.weekday(), d.toordinal() - date(d.year, 1, 1).toordinal() + 1, -1))``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	442
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444 .. method:: date.toordinal()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446 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	447 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	448 ``date.fromordinal(d.toordinal()) == d``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	449
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451 .. method:: date.weekday()
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 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	454 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	455 :meth:`isoweekday`.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458 .. method:: date.isoweekday()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460 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	461 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	462 :meth:`weekday`, :meth:`isocalendar`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	464
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	465 .. method:: date.isocalendar()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 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	468
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469 The ISO calendar is a widely used variant of the Gregorian calendar. See
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	470 http://www.phys.uu.nl/ vgent/calendar/isocalendar.htm for a good explanation.
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 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	473 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	474 (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	475 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	476
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477 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	478 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	479 ``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	480 4).isocalendar() == (2004, 1, 7)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481
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 .. method:: date.isoformat()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485 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	486 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	487
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	488
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489 .. method:: date.__str__()
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 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	492
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494 .. method:: date.ctime()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496 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	497 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	498 ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the native C
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499 :cfunc:`ctime` function (which :func:`time.ctime` invokes, but which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	500 :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	501
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503 .. method:: date.strftime(format)
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 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	506 Format codes referring to hours, minutes or seconds will see 0 values. See
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507 section :ref:`strftime-behavior`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	509 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	510
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	511 >>> import time
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	512 >>> 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	513 >>> 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	514 >>> today
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	515 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	516 >>> 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	517 True
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	518 >>> 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	519 >>> 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	520 ... 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	521 >>> my_birthday
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	522 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	523 >>> 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	524 >>> 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	525 202
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	526
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	527 Example of working with :class:`date`:
f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	528
f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	529 .. doctest::
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	530
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	531 >>> 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	532 >>> 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	533 >>> d
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	534 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	535 >>> t = d.timetuple()
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	536 >>> 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	537 ... print i
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	538 2002 # year
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	539 3 # month
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	540 11 # day
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	541 0
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	542 0
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	543 0
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	544 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	545 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	546 -1
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	547 >>> ic = d.isocalendar()
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	548 >>> for i in ic: # doctest: +SKIP
f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	549 ... 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	550 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	551 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	552 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	553 >>> d.isoformat()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	554 '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	555 >>> 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	556 '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	557 >>> 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	558 '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	559
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	560
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	561 .. _datetime-datetime:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	562
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563 :class:`datetime` Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	564 -------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	565
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	566 A :class:`datetime` object is a single object containing all the information
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	567 from a :class:`date` object and a :class:`time` object. Like a :class:`date`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	568 object, :class:`datetime` assumes the current Gregorian calendar extended in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569 both directions; like a time object, :class:`datetime` assumes there are exactly
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	570 3600\*24 seconds in every day.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	571
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572 Constructor:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	573
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	574
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575 .. 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	576
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577 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	578 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	579 longs, in the following ranges:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581 * ``MINYEAR <= year <= MAXYEAR``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582 * ``1 <= month <= 12``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583 * ``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	584 * ``0 <= hour < 24``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585 * ``0 <= minute < 60``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	586 * ``0 <= second < 60``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	587 * ``0 <= microsecond < 1000000``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589 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	590
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	591 Other constructors, all class methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	592
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	593
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	594 .. method:: datetime.today()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	595
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	596 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	597 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	598 :meth:`fromtimestamp`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	599
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	600
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	601 .. method:: datetime.now([tz])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	602
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	603 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	604 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	605 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	606 (for example, this may be possible on platforms supplying the C
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	607 :cfunc:`gettimeofday` function).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	608
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	609 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	610 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	611 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	612 See also :meth:`today`, :meth:`utcnow`.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	615 .. method:: datetime.utcnow()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	616
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	617 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	618 :meth:`now`, but returns the current UTC date and time, as a naive
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	619 :class:`datetime` object. See also :meth:`now`.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	622 .. method:: datetime.fromtimestamp(timestamp[, tz])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	623
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	624 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	625 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	626 specified, the timestamp is converted to the platform's local date and time, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	627 the returned :class:`datetime` object is naive.
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 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	630 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	631 equivalent to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632 ``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	633
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	634 :meth:`fromtimestamp` may raise :exc:`ValueError`, if the timestamp is out of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	635 the range of values supported by the platform C :cfunc:`localtime` or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	636 :cfunc:`gmtime` functions. It's common for this to be restricted to years in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	637 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	638 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	639 and then it's possible to have two timestamps differing by a second that yield
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	640 identical :class:`datetime` objects. See also :meth:`utcfromtimestamp`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	641
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 .. method:: datetime.utcfromtimestamp(timestamp)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	644
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	645 Return the UTC :class:`datetime` corresponding to the POSIX timestamp, with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	646 :attr:`tzinfo` ``None``. This may raise :exc:`ValueError`, if the timestamp is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	647 out of the range of values supported by the platform C :cfunc:`gmtime` function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	648 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	649 :meth:`fromtimestamp`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	650
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	651
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	652 .. method:: datetime.fromordinal(ordinal)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	654 Return the :class:`datetime` corresponding to the proleptic Gregorian ordinal,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	655 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	656 <= 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	657 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	658
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	659
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	660 .. method:: datetime.combine(date, time)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	661
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	662 Return a new :class:`datetime` object whose date members are equal to the given
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	663 :class:`date` object's, and whose time and :attr:`tzinfo` members are equal to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664 the given :class:`time` object's. For any :class:`datetime` object d, ``d ==
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665 datetime.combine(d.date(), d.timetz())``. If date is a :class:`datetime`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	666 object, its time and :attr:`tzinfo` members are ignored.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	669 .. method:: datetime.strptime(date_string, format)
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 a :class:`datetime` corresponding to date_string, parsed according to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672 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	673 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	674 can't be parsed by :func:`time.strptime` or if it returns a value which isn't a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675 time tuple.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	676
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	677 .. versionadded:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	678
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679 Class attributes:
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	682 .. attribute:: datetime.min
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	683
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	684 The earliest representable :class:`datetime`, ``datetime(MINYEAR, 1, 1,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	685 tzinfo=None)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	686
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	687
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	688 .. attribute:: datetime.max
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	689
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	690 The latest representable :class:`datetime`, ``datetime(MAXYEAR, 12, 31, 23, 59,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	691 59, 999999, tzinfo=None)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	692
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	693
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	694 .. attribute:: datetime.resolution
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	695
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	696 The smallest possible difference between non-equal :class:`datetime` objects,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	697 ``timedelta(microseconds=1)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	699 Instance attributes (read-only):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702 .. attribute:: datetime.year
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	703
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704 Between :const:`MINYEAR` and :const:`MAXYEAR` inclusive.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	707 .. attribute:: datetime.month
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	708
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	709 Between 1 and 12 inclusive.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	710
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	711
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	712 .. attribute:: datetime.day
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	713
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	714 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	715
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 .. attribute:: datetime.hour
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	718
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719 In ``range(24)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	720
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	721
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	722 .. attribute:: datetime.minute
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724 In ``range(60)``.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727 .. attribute:: datetime.second
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	728
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	729 In ``range(60)``.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732 .. attribute:: datetime.microsecond
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734 In ``range(1000000)``.
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.tzinfo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	739 The object passed as the tzinfo argument to the :class:`datetime` constructor,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	740 or ``None`` if none was passed.
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 Supported operations:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744 +---------------------------------------+-------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745 \| Operation \| Result \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746 +=======================================+===============================+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747 \| ``datetime2 = datetime1 + timedelta`` \| \(1) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748 +---------------------------------------+-------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749 \| ``datetime2 = datetime1 - timedelta`` \| \(2) \|
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 \| ``timedelta = datetime1 - datetime2`` \| \(3) \|
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 \| ``datetime1 < datetime2`` \| Compares :class:`datetime` to \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754 \| \| :class:`datetime`. (4) \|
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	757 (1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	758 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	759 time if ``timedelta.days`` > 0, or backward if ``timedelta.days`` < 0. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	760 result has the same :attr:`tzinfo` member as the input datetime, and datetime2 -
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	761 datetime1 == timedelta after. :exc:`OverflowError` is raised if datetime2.year
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	762 would be smaller than :const:`MINYEAR` or larger than :const:`MAXYEAR`. Note
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	763 that no time zone adjustments are done even if the input is an aware object.
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 (2)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	766 Computes the datetime2 such that datetime2 + timedelta == datetime1. As for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767 addition, the result has the same :attr:`tzinfo` member as the input datetime,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768 and no time zone adjustments are done even if the input is aware. This isn't
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769 quite equivalent to datetime1 + (-timedelta), because -timedelta in isolation
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	770 can overflow in cases where datetime1 - timedelta does not.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772 (3)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773 Subtraction of a :class:`datetime` from a :class:`datetime` is defined only if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774 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	775 naive, :exc:`TypeError` is raised.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	776
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777 If both are naive, or both are aware and have the same :attr:`tzinfo` member,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	778 the :attr:`tzinfo` members are ignored, and the result is a :class:`timedelta`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	779 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	780 are done in this case.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	781
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782 If both are aware and have different :attr:`tzinfo` members, ``a-b`` acts as if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	783 a and b were first converted to naive UTC datetimes first. The result is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784 ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) -
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	785 b.utcoffset())`` except that the implementation never overflows.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	786
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787 (4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	788 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	789 datetime2 in time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	790
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	791 If one comparand is naive and the other is aware, :exc:`TypeError` is raised.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	792 If both comparands are aware, and have the same :attr:`tzinfo` member, the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	793 common :attr:`tzinfo` member is ignored and the base datetimes are compared. If
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	794 both comparands are aware and have different :attr:`tzinfo` members, the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	795 comparands are first adjusted by subtracting their UTC offsets (obtained from
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	796 ``self.utcoffset()``).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	798 .. note::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	799
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	800 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	801 object addresses, datetime comparison normally raises :exc:`TypeError` if the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	802 other comparand isn't also a :class:`datetime` object. However,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	803 ``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	804 :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	805 chance at implementing mixed-type comparison. If not, when a :class:`datetime`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	806 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	807 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	808 :const:`False` or :const:`True`, respectively.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	809
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	810 :class:`datetime` objects can be used as dictionary keys. In Boolean contexts,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	811 all :class:`datetime` objects are considered to be true.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	812
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	813 Instance methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	814
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 .. method:: datetime.date()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	817
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	818 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	819
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	820
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	821 .. method:: datetime.time()
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 Return :class:`time` object with same hour, minute, second and microsecond.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	824 :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	825
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	826
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	827 .. method:: datetime.timetz()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	828
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	829 Return :class:`time` object with same hour, minute, second, microsecond, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	830 tzinfo members. See also method :meth:`time`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	831
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	832
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	833 .. 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	834
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	835 Return a datetime with the same members, except for those members given new
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	836 values by whichever keyword arguments are specified. Note that ``tzinfo=None``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	837 can be specified to create a naive datetime from an aware datetime with no
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	838 conversion of date and time members.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	839
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	840
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	841 .. method:: datetime.astimezone(tz)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	842
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	843 Return a :class:`datetime` object with new :attr:`tzinfo` member tz, adjusting
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	844 the date and time members so the result is the same UTC time as self, but in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	845 tz's local time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	846
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	847 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	848 :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	849 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	850 not return ``None``).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	851
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	852 If ``self.tzinfo`` is tz, ``self.astimezone(tz)`` is equal to self: no
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	853 adjustment of date or time members is performed. Else the result is local time
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	854 in time zone tz, representing the same UTC time as self: after ``astz =
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	855 dt.astimezone(tz)``, ``astz - astz.utcoffset()`` will usually have the same date
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	856 and time members as ``dt - dt.utcoffset()``. The discussion of class
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	857 :class:`tzinfo` explains the cases at Daylight Saving Time transition boundaries
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	858 where this cannot be achieved (an issue only if tz models both standard and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	859 daylight time).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	860
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	861 If you merely want to attach a time zone object tz to a datetime dt without
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	862 adjustment of date and time members, use ``dt.replace(tzinfo=tz)``. If you
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	863 merely want to remove the time zone object from an aware datetime dt without
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	864 conversion of date and time members, use ``dt.replace(tzinfo=None)``.
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 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	867 :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	868 Ignoring error cases, :meth:`astimezone` acts like::
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 def astimezone(self, tz):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	871 if self.tzinfo is tz:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	872 return self
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	873 # 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	874 utc = (self - self.utcoffset()).replace(tzinfo=tz)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	875 # 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	876 return tz.fromutc(utc)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	877
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	878
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	879 .. method:: datetime.utcoffset()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	880
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	881 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	882 ``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	883 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	884 minutes with magnitude less than one day.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	885
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	886
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	887 .. method:: datetime.dst()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	888
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	889 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	890 ``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	891 ``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	892 with magnitude less than one day.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	893
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	894
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	895 .. method:: datetime.tzname()
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 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	898 ``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	899 ``None`` or a string object,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	900
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 .. method:: datetime.timetuple()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	903
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	904 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	905 ``d.timetuple()`` is equivalent to ``time.struct_time((d.year, d.month, d.day,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	906 d.hour, d.minute, d.second, d.weekday(), d.toordinal() - date(d.year, 1,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	907 1).toordinal() + 1, dst))`` The :attr:`tm_isdst` flag of the result is set
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	908 according to the :meth:`dst` method: :attr:`tzinfo` is ``None`` or :meth:`dst`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	909 returns ``None``, :attr:`tm_isdst` is set to ``-1``; else if :meth:`dst`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	910 returns a non-zero value, :attr:`tm_isdst` is set to ``1``; else ``tm_isdst`` is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	911 set to ``0``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	912
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	913
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	914 .. method:: datetime.utctimetuple()
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 If :class:`datetime` instance d is naive, this is the same as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	917 ``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	918 ``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	919
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	920 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	921 ``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	922 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	923 :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	924 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	925 boundary.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	926
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 .. method:: datetime.toordinal()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	929
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	930 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	931 ``self.date().toordinal()``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	932
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	933
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	934 .. method:: datetime.weekday()
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 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	937 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	938
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	939
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	940 .. method:: datetime.isoweekday()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	941
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	942 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	943 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	944 :meth:`isocalendar`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	945
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 .. method:: datetime.isocalendar()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	948
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	949 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	950 ``self.date().isocalendar()``.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	953 .. method:: datetime.isoformat([sep])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	954
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	955 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	956 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	957 YYYY-MM-DDTHH:MM:SS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	958
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	959 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	960 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	961 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	962 YYYY-MM-DDTHH:MM:SS+HH:MM
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 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	965 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	966
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	967 >>> from datetime import tzinfo, timedelta, datetime
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	968 >>> class TZ(tzinfo):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	969 ... 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	970 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	971 >>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	972 '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	973
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	974
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	975 .. method:: datetime.__str__()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	976
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	977 For a :class:`datetime` instance d, ``str(d)`` is equivalent to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	978 ``d.isoformat(' ')``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	979
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 .. method:: datetime.ctime()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	982
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	983 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	984 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	985 equivalent to ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	986 native C :cfunc:`ctime` function (which :func:`time.ctime` invokes, but which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	987 :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	988
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 .. method:: datetime.strftime(format)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	991
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	992 Return a string representing the date and time, controlled by an explicit format
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	993 string. See section :ref:`strftime-behavior`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	994
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	995 Examples of working with datetime objects:
f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	996
f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	997 .. doctest::
f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	998
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	999 >>> 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	1000 >>> # 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	1001 >>> 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	1002 >>> 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	1003 >>> 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	1004 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	1005 >>> # Using datetime.now() or datetime.utcnow()
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1006 >>> 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	1007 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	1008 >>> 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	1009 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	1010 >>> # 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	1011 >>> 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	1012 >>> dt
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1013 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	1014 >>> # 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	1015 >>> tt = dt.timetuple()
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1016 >>> 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	1017 ... 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	1018 ...
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1019 2006 # year
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1020 11 # month
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1021 21 # day
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1022 16 # hour
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1023 30 # minute
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1024 0 # second
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1025 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	1026 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	1027 -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	1028 >>> # 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	1029 >>> ic = dt.isocalendar()
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1030 >>> 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	1031 ... print it
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1032 ...
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1033 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	1034 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	1035 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	1036 >>> # Formatting datetime
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1037 >>> 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	1038 '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	1039
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1040 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	1041
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1042 >>> 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	1043 >>> 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	1044 ... def __init__(self): # DST starts last Sunday in March
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1045 ... 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	1046 ... 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	1047 ... 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	1048 ... 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	1049 ... def utcoffset(self, dt):
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1050 ... return timedelta(hours=1) + self.dst(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	1051 ... 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	1052 ... 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	1053 ... 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	1054 ... else:
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1055 ... 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	1056 ... 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	1057 ... 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	1058 ...
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1059 >>> class GMT2(tzinfo):
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1060 ... def __init__(self):
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	1061 ... 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	1062 ... 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	1063 ... 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	1064 ... 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	1065 ... def utcoffset(self, dt):
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1066 ... return timedelta(hours=1) + self.dst(dt)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1067 ... def dst(self, dt):
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1068 ... 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	1069 ... return timedelta(hours=2)
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1070 ... else:
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1071 ... 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	1072 ... 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	1073 ... 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	1074 ...
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1075 >>> gmt1 = GMT1()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1076 >>> # 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	1077 >>> 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	1078 >>> dt1.dst()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1079 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	1080 >>> dt1.utcoffset()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1081 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	1082 >>> 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	1083 >>> dt2.dst()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1084 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	1085 >>> dt2.utcoffset()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1086 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	1087 >>> # 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	1088 >>> 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	1089 >>> 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	1090 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	1091 >>> 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	1092 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	1093 >>> 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	1094 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	1095
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1096
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1097
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1098 .. _datetime-time:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1099
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1100 :class:`time` Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1101 ---------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1102
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1103 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	1104 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	1105
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1106
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1107 .. class:: time(hour[, minute[, second[, microsecond[, tzinfo]]]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1108
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1109 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	1110 :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	1111 following ranges:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1112
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1113 * ``0 <= hour < 24``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1114 * ``0 <= minute < 60``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1115 * ``0 <= second < 60``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1116 * ``0 <= microsecond < 1000000``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1117
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1118 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	1119 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	1120
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1121 Class attributes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1122
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1123
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1124 .. attribute:: time.min
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1125
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1126 The earliest representable :class:`time`, ``time(0, 0, 0, 0)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1127
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1128
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1129 .. attribute:: time.max
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1130
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1131 The latest representable :class:`time`, ``time(23, 59, 59, 999999)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1132
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1133
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1134 .. attribute:: time.resolution
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1135
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1136 The smallest possible difference between non-equal :class:`time` objects,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1137 ``timedelta(microseconds=1)``, although note that arithmetic on :class:`time`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1138 objects is not supported.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1139
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1140 Instance attributes (read-only):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1141
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1142
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1143 .. attribute:: time.hour
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1144
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1145 In ``range(24)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1146
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1147
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1148 .. attribute:: time.minute
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1149
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1150 In ``range(60)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1151
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 .. attribute:: time.second
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1154
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1155 In ``range(60)``.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1158 .. attribute:: time.microsecond
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1159
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1160 In ``range(1000000)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1161
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 .. attribute:: time.tzinfo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1164
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1165 The object passed as the tzinfo argument to the :class:`time` constructor, or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1166 ``None`` if none was passed.
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 Supported operations:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1169
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1170 * comparison of :class:`time` to :class:`time`, where a is considered less
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1171 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	1172 is aware, :exc:`TypeError` is raised. If both comparands are aware, and have
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1173 the same :attr:`tzinfo` member, the common :attr:`tzinfo` member is ignored and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1174 the base times are compared. If both comparands are aware and have different
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1175 :attr:`tzinfo` members, the comparands are first adjusted by subtracting their
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1176 UTC offsets (obtained from ``self.utcoffset()``). In order to stop mixed-type
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1177 comparisons from falling back to the default comparison by object address, when
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1178 a :class:`time` object is compared to an object of a different type,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1179 :exc:`TypeError` is raised unless the comparison is ``==`` or ``!=``. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1180 latter cases return :const:`False` or :const:`True`, respectively.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1181
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1182 * hash, use as dict key
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 * efficient pickling
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1185
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1186 * in Boolean contexts, a :class:`time` object is considered to be true if and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1187 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	1188 ``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	1189
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1190 Instance methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1191
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 .. 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	1194
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1195 Return a :class:`time` with the same value, except for those members given new
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1196 values by whichever keyword arguments are specified. Note that ``tzinfo=None``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1197 can be specified to create a naive :class:`time` from an aware :class:`time`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1198 without conversion of the time members.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1201 .. method:: time.isoformat()
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 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	1204 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	1205 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	1206 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	1207
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1208
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1209 .. method:: time.__str__()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1210
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1211 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	1212
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1213
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1214 .. method:: time.strftime(format)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1215
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1216 Return a string representing the time, controlled by an explicit format string.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1217 See section :ref:`strftime-behavior`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1218
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1219
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1220 .. method:: time.utcoffset()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1221
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1222 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	1223 ``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	1224 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	1225 minutes with magnitude less than one day.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1226
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1227
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1228 .. method:: time.dst()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1229
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1230 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	1231 ``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	1232 ``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	1233 with magnitude less than one day.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1236 .. method:: time.tzname()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1237
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1238 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	1239 ``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	1240 return ``None`` or a string object.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1241
46011 f2ab50d0fa90 Test doctests in datetime docs. Georg Brandl <georg@python.org> parents: 45767 diff changeset	1242 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	1243
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1244 >>> 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	1245 >>> 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	1246 ... 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	1247 ... 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	1248 ... 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	1249 ... 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	1250 ... 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	1251 ... 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	1252 ...
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1253 >>> 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	1254 >>> 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	1255 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	1256 >>> gmt = GMT1()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1257 >>> t.isoformat()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1258 '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	1259 >>> t.dst()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1260 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	1261 >>> t.tzname()
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1262 'Europe/Prague'
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1263 >>> 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	1264 '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	1265
42604 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 .. _datetime-tzinfo:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1268
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1269 :class:`tzinfo` Objects
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
51156 a3304190d8aa Minor spelling mistake in datetime docs. Brett Cannon <bcannon@gmail.com> parents: 50869 diff changeset	1272 :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	1273 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	1274 supply implementations of the standard :class:`tzinfo` methods needed by the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1275 :class:`datetime` methods you use. The :mod:`datetime` module does not supply
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1276 any concrete subclasses of :class:`tzinfo`.
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 An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1279 constructors for :class:`datetime` and :class:`time` objects. The latter objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1280 view their members as being in local time, and the :class:`tzinfo` object
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1281 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	1282 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	1283
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1284 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	1285 :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	1286 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	1287 may be relaxed in the future.
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 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	1290 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	1291 :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	1292
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1293
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1294 .. method:: tzinfo.utcoffset(self, dt)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1295
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1296 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	1297 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	1298 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	1299 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	1300 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	1301 :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	1302 -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	1303 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	1304 like one of these two::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1305
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1306 return CONSTANT # fixed-offset class
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1307 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	1308
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1309 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	1310 ``None`` either.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1311
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1312 The default implementation of :meth:`utcoffset` raises
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1313 :exc:`NotImplementedError`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1314
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1315
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1316 .. method:: tzinfo.dst(self, dt)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1317
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1318 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	1319 ``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	1320 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	1321 (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	1322 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	1323 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	1324 separately. For example, :meth:`datetime.timetuple` calls its :attr:`tzinfo`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1325 member's :meth:`dst` method to determine how the :attr:`tm_isdst` flag should be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1326 set, and :meth:`tzinfo.fromutc` calls :meth:`dst` to account for DST changes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1327 when crossing time zones.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1328
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1329 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	1330 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	1331
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1332 ``tz.utcoffset(dt) - tz.dst(dt)``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1333
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1334 must return the same result for every :class:`datetime` dt with ``dt.tzinfo ==
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1335 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	1336 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	1337 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	1338 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	1339 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	1340 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	1341 :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	1342
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1343 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	1344
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1345 def dst(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1346 # 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	1347 return timedelta(0)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1348
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1349 or ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1350
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1351 def dst(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1352 # 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	1353 # 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	1354 # in standard local time. Then
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1355
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1356 if dston <= dt.replace(tzinfo=None) < dstoff:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1357 return timedelta(hours=1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1358 else:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1359 return timedelta(0)
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 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	1362
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 .. method:: tzinfo.tzname(self, dt)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1365
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1366 Return the time zone name corresponding to the :class:`datetime` object dt, as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1367 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	1368 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	1369 "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	1370 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	1371 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	1372 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	1373 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	1374 daylight time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1375
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1376 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	1377
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1378 These methods are called by a :class:`datetime` or :class:`time` object, in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1379 response to their methods of the same names. A :class:`datetime` object passes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1380 itself as the argument, and a :class:`time` object passes ``None`` as the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1381 argument. A :class:`tzinfo` subclass's methods should therefore be prepared to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1382 accept a dt argument of ``None``, or of class :class:`datetime`.
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 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	1385 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	1386 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	1387 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	1388 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	1389
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1390 When a :class:`datetime` object is passed in response to a :class:`datetime`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1391 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	1392 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	1393 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	1394 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	1395
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1396 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	1397
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1398
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1399 .. method:: tzinfo.fromutc(self, dt)
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 This is called from the default :class:`datetime.astimezone()` implementation.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1402 When called from that, ``dt.tzinfo`` is self, and dt's date and time members
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1403 are to be viewed as expressing a UTC time. The purpose of :meth:`fromutc` is to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1404 adjust the date and time members, returning an equivalent datetime in self's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1405 local time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1406
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1407 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	1408 :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	1409 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	1410 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	1411 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	1412 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	1413 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	1414 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	1415 :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	1416 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	1417
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1418 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	1419 like::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1420
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1421 def fromutc(self, dt):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1422 # 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	1423 dtoff = dt.utcoffset()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1424 dtdst = dt.dst()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1425 # 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	1426 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	1427 if delta:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1428 dt += delta # convert to standard local time
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1429 dtdst = dt.dst()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1430 # raise ValueError if dtdst is None
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1431 if dtdst:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1432 return dt + dtdst
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1433 else:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1434 return dt
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1435
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1436 Example :class:`tzinfo` classes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1437
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1438 .. literalinclude:: ../includes/tzinfo-examples.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1439
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1440
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1441 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	1442 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	1443 points. For concreteness, consider US Eastern (UTC -0500), where EDT begins the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1444 minute after 1:59 (EST) on the first Sunday in April, and ends the minute after
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1445 1:59 (EDT) on the last Sunday in October::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1446
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1447 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	1448 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	1449 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	1450
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1451 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	1452
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1453 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	1454
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1455 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	1456 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	1457 ``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	1458 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	1459 :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	1460 Eastern) to be in daylight time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1461
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1462 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	1463 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	1464 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	1465 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	1466 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	1467 :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	1468 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	1469 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	1470 :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	1471 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	1472 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	1473 standard local time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1474
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1475 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	1476 :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	1477 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	1478 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	1479
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1480
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1481 .. _strftime-behavior:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1482
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1483 :meth:`strftime` Behavior
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1484 -------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1485
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1486 :class:`date`, :class:`datetime`, and :class:`time` objects all support a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1487 ``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	1488 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	1489 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	1490 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	1491
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1492 For :class:`time` objects, the format codes for year, month, and day should not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1493 be used, as time objects have no such values. If they're used anyway, ``1900``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1494 is substituted for the year, and ``0`` for the month and day.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1495
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1496 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	1497 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	1498 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	1499
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1500 .. versionadded:: 2.6
50869 d71583860634 #4923: clarify what was added. Georg Brandl <georg@python.org> parents: 50522 diff changeset	1501 :class:`time` and :class:`datetime` objects support a ``%f`` format code
d71583860634 #4923: clarify what was added. Georg Brandl <georg@python.org> parents: 50522 diff changeset	1502 which expands to the number of microseconds in the object, zero-padded on
d71583860634 #4923: clarify what was added. Georg Brandl <georg@python.org> parents: 50522 diff changeset	1503 the left to six places.
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1504
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1505 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	1506 strings.
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1507
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1508 For an aware object:
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1509
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1510 ``%z``
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1511 :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	1512 -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	1513 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	1514 :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	1515 replaced with the string ``'-0330'``.
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1516
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1517 ``%Z``
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1518 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	1519 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	1520
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1521 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	1522 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	1523 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	1524
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1525 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	1526 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	1527 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	1528 format codes.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1529
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1530 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	1531 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	1532
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1533 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1534 \| 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	1535 +===========+================================+=======+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1536 \| ``%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	1537 \| \| name. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1538 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1539 \| ``%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	1540 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1541 \| ``%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	1542 \| \| name. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1543 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1544 \| ``%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	1545 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1546 \| ``%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	1547 \| \| time representation. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1548 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1549 \| ``%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	1550 \| \| 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	1551 +-----------+--------------------------------+-------+
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1552 \| ``%f`` \| Microsecond as a decimal \| \(1) \|
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1553 \| \| number [0,999999], zero-padded \| \|
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1554 \| \| on the left \| \|
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1555 +-----------+--------------------------------+-------+
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1556 \| ``%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	1557 \| \| 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	1558 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1559 \| ``%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	1560 \| \| 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	1561 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1562 \| ``%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	1563 \| \| 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	1564 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1565 \| ``%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	1566 \| \| [01,12]. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1567 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1568 \| ``%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	1569 \| \| [00,59]. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1570 +-----------+--------------------------------+-------+
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1571 \| ``%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	1572 \| \| 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	1573 +-----------+--------------------------------+-------+
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1574 \| ``%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	1575 \| \| [00,61]. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1576 +-----------+--------------------------------+-------+
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1577 \| ``%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	1578 \| \| (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	1579 \| \| 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	1580 \| \| [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	1581 \| \| 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	1582 \| \| 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	1583 \| \| week 0. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1584 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1585 \| ``%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	1586 \| \| [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	1587 +-----------+--------------------------------+-------+
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1588 \| ``%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	1589 \| \| (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	1590 \| \| 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	1591 \| \| [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	1592 \| \| 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	1593 \| \| 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	1594 \| \| week 0. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1595 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1596 \| ``%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	1597 \| \| representation. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1598 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1599 \| ``%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	1600 \| \| representation. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1601 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1602 \| ``%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	1603 \| \| 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	1604 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1605 \| ``%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	1606 \| \| number. \| \|
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1607 +-----------+--------------------------------+-------+
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1608 \| ``%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	1609 \| \| 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	1610 \| \| 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	1611 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1612 \| ``%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	1613 \| \| 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	1614 +-----------+--------------------------------+-------+
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1615 \| ``%%`` \| 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	1616 +-----------+--------------------------------+-------+
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1617
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1618 Notes:
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1619
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1620 (1)
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1621 When used with the :func:`strptime` function, the ``%f`` directive
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1622 accepts from one to six digits and zero pads on the right. ``%f`` is
50869 d71583860634 #4923: clarify what was added. Georg Brandl <georg@python.org> parents: 50522 diff changeset	1623 an extension to the set of format characters in the C standard (but
d71583860634 #4923: clarify what was added. Georg Brandl <georg@python.org> parents: 50522 diff changeset	1624 implemented separately in datetime objects, and therefore always
d71583860634 #4923: clarify what was added. Georg Brandl <georg@python.org> parents: 50522 diff changeset	1625 available).
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1626
212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1627 (2)
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1628 When used with the :func:`strptime` function, the ``%p`` directive only affects
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1629 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	1630
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1631 (3)
52723 8d84f220ff27 Clarify that datetime strftime does not produce leap seconds and datetime R. David Murray <rdmurray@bitdance.com> parents: 51156 diff changeset	1632 The range really is ``0`` to ``61``; according to the Posix standard this
8d84f220ff27 Clarify that datetime strftime does not produce leap seconds and datetime R. David Murray <rdmurray@bitdance.com> parents: 51156 diff changeset	1633 accounts for leap seconds and the (very rare) double leap seconds.
8d84f220ff27 Clarify that datetime strftime does not produce leap seconds and datetime R. David Murray <rdmurray@bitdance.com> parents: 51156 diff changeset	1634 The :mod:`time` module may produce and does accept leap seconds since
8d84f220ff27 Clarify that datetime strftime does not produce leap seconds and datetime R. David Murray <rdmurray@bitdance.com> parents: 51156 diff changeset	1635 it is based on the Posix standard, but the :mod:`datetime` module
8d84f220ff27 Clarify that datetime strftime does not produce leap seconds and datetime R. David Murray <rdmurray@bitdance.com> parents: 51156 diff changeset	1636 does not accept leap seconds in :func:`strptime` input nor will it
8d84f220ff27 Clarify that datetime strftime does not produce leap seconds and datetime R. David Murray <rdmurray@bitdance.com> parents: 51156 diff changeset	1637 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	1638
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1639 (4)
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1640 When used with the :func:`strptime` function, ``%U`` and ``%W`` are only used in
03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1641 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	1642
45767 212e9c8ad087 add %f format to datetime - issue 1158 Skip Montanaro <skip@pobox.com> parents: 44383 diff changeset	1643 (5)
44221 03945a1d4fb3 Add examples to the datetime documentation. Written for GHOP by "h4wk.cz". Georg Brandl <georg@python.org> parents: 43753 diff changeset	1644 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	1645 ``%z`` is replaced with the string ``'-0330'``.

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/datetime.rst @ 54294:dba767bc3155 legacy-trunk