cpython-lru_cache-weakref: Doc/lib/libdatetime.tex annotate

annotate Doc/lib/libdatetime.tex @ 39042:c02fa187e0f4 legacy-trunk

Part of SF patch #1484695. This removes dead code. The chksum was already verified in .frombuf() on the lines above. If there was a problem an exception is raised, so there was no way this condition could have been true.

author	Neal Norwitz <nnorwitz@gmail.com>
date	Mon, 10 Jul 2006 00:23:17 +0000
parents	5203376f1589
children	e7a58341b2e8

rev	line source
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1 % XXX what order should the types be discussed in?
26876 35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	2
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	3 \section{\module{datetime} ---
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	4 Basic date and time types}
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	5
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	6 \declaremodule{builtin}{datetime}
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	7 \modulesynopsis{Basic date and time types.}
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	8 \moduleauthor{Tim Peters}{tim@zope.com}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	9 \sectionauthor{Tim Peters}{tim@zope.com}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	10 \sectionauthor{A.M. Kuchling}{amk@amk.ca}
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	11
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	12 \versionadded{2.3}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	13
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	14
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	15 The \module{datetime} module supplies classes for manipulating dates
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	16 and times in both simple and complex ways. While date and time
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	17 arithmetic is supported, the focus of the implementation is on
27185 c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	18 efficient member extraction for output formatting and manipulation.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	19
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	20 There are two kinds of date and time objects: ``naive'' and ``aware''.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	21 This distinction refers to whether the object has any notion of time
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	22 zone, daylight saving time, or other kind of algorithmic or political
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	23 time adjustment. Whether a naive \class{datetime} object represents
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	24 Coordinated Universal Time (UTC), local time, or time in some other
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	25 timezone is purely up to the program, just like it's up to the program
34448 a063f0d6db28 fix a bunch of spelling errors Fred Drake <fdrake@acm.org> parents: 34420 diff changeset	26 whether a particular number represents metres, miles, or mass. Naive
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	27 \class{datetime} objects are easy to understand and to work with, at
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	28 the cost of ignoring some aspects of reality.
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	29
27185 c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	30 For applications requiring more, \class{datetime} and \class{time}
c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	31 objects have an optional time zone information member,
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	32 \member{tzinfo}, that can contain an instance of a subclass of
27185 c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	33 the abstract \class{tzinfo} class. These \class{tzinfo} objects
c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	34 capture information about the offset from UTC time, the time zone
c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	35 name, and whether Daylight Saving Time is in effect. Note that no
c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	36 concrete \class{tzinfo} classes are supplied by the \module{datetime}
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	37 module. Supporting timezones at whatever level of detail is required
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	38 is up to the application. The rules for time adjustment across the
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	39 world are more political than rational, and there is no standard
27185 c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	40 suitable for every application.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	41
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	42 The \module{datetime} module exports the following constants:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	43
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	44 \begin{datadesc}{MINYEAR}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	45 The smallest year number allowed in a \class{date} or
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	46 \class{datetime} object. \constant{MINYEAR}
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	47 is \code{1}.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	48 \end{datadesc}
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	49
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	50 \begin{datadesc}{MAXYEAR}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	51 The largest year number allowed in a \class{date} or \class{datetime}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	52 object. \constant{MAXYEAR} is \code{9999}.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	53 \end{datadesc}
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	54
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	55 \begin{seealso}
26965 b790da0671f7 Spelling fix Raymond Hettinger <python@rcn.com> parents: 26962 diff changeset	56 \seemodule{calendar}{General calendar related functions.}
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	57 \seemodule{time}{Time access and conversions.}
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	58 \end{seealso}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	59
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	60 \subsection{Available Types}
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	61
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	62 \begin{classdesc*}{date}
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	63 An idealized naive date, assuming the current Gregorian calendar
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	64 always was, and always will be, in effect.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	65 Attributes: \member{year}, \member{month}, and \member{day}.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	66 \end{classdesc*}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	67
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	68 \begin{classdesc*}{time}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	69 An idealized time, independent of any particular day, assuming
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	70 that every day has exactly 246060 seconds (there is no notion
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	71 of "leap seconds" here).
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	72 Attributes: \member{hour}, \member{minute}, \member{second},
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	73 \member{microsecond}, and \member{tzinfo}.
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	74 \end{classdesc*}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	75
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	76 \begin{classdesc*}{datetime}
27185 c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	77 A combination of a date and a time.
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	78 Attributes: \member{year}, \member{month}, \member{day},
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	79 \member{hour}, \member{minute}, \member{second},
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	80 \member{microsecond}, and \member{tzinfo}.
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	81 \end{classdesc*}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	82
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	83 \begin{classdesc*}{timedelta}
27185 c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	84 A duration expressing the difference between two \class{date},
c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	85 \class{time}, or \class{datetime} instances to microsecond
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	86 resolution.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	87 \end{classdesc*}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	88
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	89 \begin{classdesc*}{tzinfo}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	90 An abstract base class for time zone information objects. These
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	91 are used by the \class{datetime} and \class{time} classes to
27185 c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	92 provide a customizable notion of time adjustment (for example, to
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	93 account for time zone and/or daylight saving time).
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	94 \end{classdesc*}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	95
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	96 Objects of these types are immutable.
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	97
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	98 Objects of the \class{date} type are always naive.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	99
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	100 An object \var{d} of type \class{time} or \class{datetime} may be
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	101 naive or aware. \var{d} is aware if \code{\var{d}.tzinfo} is not
27185 c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	102 \code{None} and \code{\var{d}.tzinfo.utcoffset(\var{d})} does not return
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	103 \code{None}. If \code{\var{d}.tzinfo} is \code{None}, or if
6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	104 \code{\var{d}.tzinfo} is not \code{None} but
6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	105 \code{\var{d}.tzinfo.utcoffset(\var{d})} returns \code{None}, \var{d}
6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	106 is naive.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	107
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	108 The distinction between naive and aware doesn't apply to
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	109 \class{timedelta} objects.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	110
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	111 Subclass relationships:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	112
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	113 \begin{verbatim}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	114 object
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	115 timedelta
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	116 tzinfo
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	117 time
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	118 date
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	119 datetime
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	120 \end{verbatim}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	121
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	122 \subsection{\class{timedelta} Objects \label{datetime-timedelta}}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	123
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	124 A \class{timedelta} object represents a duration, the difference
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	125 between two dates or times.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	126
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	127 \begin{classdesc}{timedelta}{\optional{days\optional{, seconds\optional{,
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	128 microseconds\optional{, milliseconds\optional{,
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	129 minutes\optional{, hours\optional{, weeks}}}}}}}}
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	130 All arguments are optional and default to \code{0}. Arguments may
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	131 be ints, longs, or floats, and may be positive or negative.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	132
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	133 Only \var{days}, \var{seconds} and \var{microseconds} are stored
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	134 internally. Arguments are converted to those units:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	135
27185 c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	136 \begin{itemize}
c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	137 \item A millisecond is converted to 1000 microseconds.
c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	138 \item A minute is converted to 60 seconds.
c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	139 \item An hour is converted to 3600 seconds.
c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	140 \item A week is converted to 7 days.
c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	141 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	142
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	143 and days, seconds and microseconds are then normalized so that the
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	144 representation is unique, with
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	145
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	146 \begin{itemize}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	147 \item \code{0 <= \var{microseconds} < 1000000}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	148 \item \code{0 <= \var{seconds} < 3600*24} (the number of seconds in one day)
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	149 \item \code{-999999999 <= \var{days} <= 999999999}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	150 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	151
27185 c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	152 If any argument is a float and there are fractional microseconds,
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	153 the fractional microseconds left over from all arguments are combined
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	154 and their sum is rounded to the nearest microsecond. If no
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	155 argument is a float, the conversion and normalization processes
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	156 are exact (no information is lost).
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	157
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	158 If the normalized value of days lies outside the indicated range,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	159 \exception{OverflowError} is raised.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	160
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	161 Note that normalization of negative values may be surprising at first.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	162 For example,
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	163
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	164 \begin{verbatim}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	165 >>> d = timedelta(microseconds=-1)
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	166 >>> (d.days, d.seconds, d.microseconds)
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	167 (-1, 86399, 999999)
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	168 \end{verbatim}
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	169 \end{classdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	170
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	171 Class attributes are:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	172
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	173 \begin{memberdesc}{min}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	174 The most negative \class{timedelta} object,
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	175 \code{timedelta(-999999999)}.
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	176 \end{memberdesc}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	177
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	178 \begin{memberdesc}{max}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	179 The most positive \class{timedelta} object,
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	180 \code{timedelta(days=999999999, hours=23, minutes=59, seconds=59,
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	181 microseconds=999999)}.
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	182 \end{memberdesc}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	183
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	184 \begin{memberdesc}{resolution}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	185 The smallest possible difference between non-equal
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	186 \class{timedelta} objects, \code{timedelta(microseconds=1)}.
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	187 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	188
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	189 Note that, because of normalization, \code{timedelta.max} \textgreater
6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	190 \code{-timedelta.min}. \code{-timedelta.max} is not representable as
6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	191 a \class{timedelta} object.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	192
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	193 Instance attributes (read-only):
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	194
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	195 \begin{tableii}{c\|l}{code}{Attribute}{Value}
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	196 \lineii{days}{Between -999999999 and 999999999 inclusive}
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	197 \lineii{seconds}{Between 0 and 86399 inclusive}
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	198 \lineii{microseconds}{Between 0 and 999999 inclusive}
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	199 \end{tableii}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	200
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	201 Supported operations:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	202
27185 c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	203 % XXX this table is too wide!
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	204 \begin{tableii}{c\|l}{code}{Operation}{Result}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	205 \lineii{\var{t1} = \var{t2} + \var{t3}}
26958 3c041b19f1d3 Removed the now-untrue (or soon-to-be untrue) part of the astimezone() Tim Peters <tim.peters@gmail.com> parents: 26951 diff changeset	206 {Sum of \var{t2} and \var{t3}.
26872 f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	207 Afterwards \var{t1}-\var{t2} == \var{t3} and \var{t1}-\var{t3}
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	208 == \var{t2} are true.
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	209 (1)}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	210 \lineii{\var{t1} = \var{t2} - \var{t3}}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	211 {Difference of \var{t2} and \var{t3}.
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	212 Afterwards \var{t1} == \var{t2} - \var{t3} and
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	213 \var{t2} == \var{t1} + \var{t3} are true.
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	214 (1)}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	215 \lineii{\var{t1} = \var{t2} * \var{i} or \var{t1} = \var{i} * \var{t2}}
26872 f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	216 {Delta multiplied by an integer or long.
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	217 Afterwards \var{t1} // i == \var{t2} is true,
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	218 provided \code{i != 0}.}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	219 \lineii{}{In general, \var{t1} * i == \var{t1} * (i-1) + \var{t1} is true.
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	220 (1)}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	221 \lineii{\var{t1} = \var{t2} // \var{i}}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	222 {The floor is computed and the remainder (if any) is thrown away.
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	223 (3)}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	224 \lineii{+\var{t1}}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	225 {Returns a \class{timedelta} object with the same value.
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	226 (2)}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	227 \lineii{-\var{t1}}
26962 b9c462d23f3c Add markup for time object. Raymond Hettinger <python@rcn.com> parents: 26958 diff changeset	228 {equivalent to \class{timedelta}(-\var{t1.days}, -\var{t1.seconds},
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	229 -\var{t1.microseconds}), and to \var{t1}* -1.
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	230 (1)(4)}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	231 \lineii{abs(\var{t})}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	232 {equivalent to +\var{t} when \code{t.days >= 0}, and to
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	233 -\var{t} when \code{t.days < 0}.
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	234 (2)}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	235 \end{tableii}
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	236 \noindent
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	237 Notes:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	238
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	239 \begin{description}
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	240 \item[(1)]
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	241 This is exact, but may overflow.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	242
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	243 \item[(2)]
27037 99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	244 This is exact, and cannot overflow.
99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	245
99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	246 \item[(3)]
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	247 Division by 0 raises \exception{ZeroDivisionError}.
26951 94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	248
27037 99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	249 \item[(4)]
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	250 -\var{timedelta.max} is not representable as a \class{timedelta} object.
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	251 \end{description}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	252
26951 94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	253 In addition to the operations listed above \class{timedelta} objects
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	254 support certain additions and subtractions with \class{date} and
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	255 \class{datetime} objects (see below).
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	256
26951 94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	257 Comparisons of \class{timedelta} objects are supported with the
94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	258 \class{timedelta} object representing the smaller duration considered
94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	259 to be the smaller timedelta.
27763 fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	260 In order to stop mixed-type comparisons from falling back to the
fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	261 default comparison by object address, when a \class{timedelta} object is
fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	262 compared to an object of a different type, \exception{TypeError} is
fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	263 raised unless the comparison is \code{==} or \code{!=}. The latter
fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	264 cases return \constant{False} or \constant{True}, respectively.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	265
27185 c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	266 \class{timedelta} objects are hashable (usable as dictionary keys),
26951 94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	267 support efficient pickling, and in Boolean contexts, a \class{timedelta}
94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	268 object is considered to be true if and only if it isn't equal to
94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	269 \code{timedelta(0)}.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	270
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	271
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	272 \subsection{\class{date} Objects \label{datetime-date}}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	273
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	274 A \class{date} object represents a date (year, month and day) in an idealized
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	275 calendar, the current Gregorian calendar indefinitely extended in both
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	276 directions. January 1 of year 1 is called day number 1, January 2 of year
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	277 1 is called day number 2, and so on. This matches the definition of the
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	278 "proleptic Gregorian" calendar in Dershowitz and Reingold's book
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	279 \citetitle{Calendrical Calculations}, where it's the base calendar for all
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	280 computations. See the book for algorithms for converting between
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	281 proleptic Gregorian ordinals and many other calendar systems.
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	282
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	283 \begin{classdesc}{date}{year, month, day}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	284 All arguments are required. Arguments may be ints or longs, in the
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	285 following ranges:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	286
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	287 \begin{itemize}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	288 \item \code{MINYEAR <= \var{year} <= MAXYEAR}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	289 \item \code{1 <= \var{month} <= 12}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	290 \item \code{1 <= \var{day} <= number of days in the given month and year}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	291 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	292
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	293 If an argument outside those ranges is given, \exception{ValueError}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	294 is raised.
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	295 \end{classdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	296
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	297 Other constructors, all class methods:
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	298
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	299 \begin{methoddesc}{today}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	300 Return the current local date. This is equivalent to
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	301 \code{date.fromtimestamp(time.time())}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	302 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	303
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	304 \begin{methoddesc}{fromtimestamp}{timestamp}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	305 Return the local date corresponding to the POSIX timestamp, such
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	306 as is returned by \function{time.time()}. This may raise
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	307 \exception{ValueError}, if the timestamp is out of the range of
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	308 values supported by the platform C \cfunction{localtime()}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	309 function. It's common for this to be restricted to years from 1970
27089 a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	310 through 2038. Note that on non-POSIX systems that include leap
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	311 seconds in their notion of a timestamp, leap seconds are ignored by
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	312 \method{fromtimestamp()}.
27184 728383dc739e Markup fix Andrew M. Kuchling <amk@amk.ca> parents: 27178 diff changeset	313 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	314
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	315 \begin{methoddesc}{fromordinal}{ordinal}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	316 Return the date corresponding to the proleptic Gregorian ordinal,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	317 where January 1 of year 1 has ordinal 1. \exception{ValueError} is
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	318 raised unless \code{1 <= \var{ordinal} <= date.max.toordinal()}.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	319 For any date \var{d}, \code{date.fromordinal(\var{d}.toordinal()) ==
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	320 \var{d}}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	321 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	322
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	323 Class attributes:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	324
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	325 \begin{memberdesc}{min}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	326 The earliest representable date, \code{date(MINYEAR, 1, 1)}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	327 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	328
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	329 \begin{memberdesc}{max}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	330 The latest representable date, \code{date(MAXYEAR, 12, 31)}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	331 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	332
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	333 \begin{memberdesc}{resolution}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	334 The smallest possible difference between non-equal date
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	335 objects, \code{timedelta(days=1)}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	336 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	337
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	338 Instance attributes (read-only):
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	339
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	340 \begin{memberdesc}{year}
27185 c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	341 Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	342 \end{memberdesc}
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	343
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	344 \begin{memberdesc}{month}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	345 Between 1 and 12 inclusive.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	346 \end{memberdesc}
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	347
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	348 \begin{memberdesc}{day}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	349 Between 1 and the number of days in the given month of the given
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	350 year.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	351 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	352
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	353 Supported operations:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	354
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	355 \begin{tableii}{c\|l}{code}{Operation}{Result}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	356 \lineii{\var{date2} = \var{date1} + \var{timedelta}}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	357 {\var{date2} is \code{\var{timedelta}.days} days removed from
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	358 \var{date1}. (1)}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	359
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	360
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	361 \lineii{\var{date2} = \var{date1} - \var{timedelta}}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	362 {Computes \var{date2} such that \code{\var{date2} + \var{timedelta}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	363 == \var{date1}}. (2)}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	364
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	365 \lineii{\var{timedelta} = \var{date1} - \var{date2}}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	366 {(3)}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	367
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	368 \lineii{\var{date1} < \var{date2}}
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	369 {\var{date1} is considered less than \var{date2} when \var{date1}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	370 precedes \var{date2} in time. (4)}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	371
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	372 \end{tableii}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	373
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	374 Notes:
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	375 \begin{description}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	376
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	377 \item[(1)]
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	378 \var{date2} is moved forward in time if \code{\var{timedelta}.days
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	379 > 0}, or backward if \code{\var{timedelta}.days < 0}. Afterward
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	380 \code{\var{date2} - \var{date1} == \var{timedelta}.days}.
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	381 \code{\var{timedelta}.seconds} and
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	382 \code{\var{timedelta}.microseconds} are ignored.
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	383 \exception{OverflowError} is raised if \code{\var{date2}.year}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	384 would be smaller than \constant{MINYEAR} or larger than
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	385 \constant{MAXYEAR}.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	386
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	387 \item[(2)]
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	388 This isn't quite equivalent to date1 +
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	389 (-timedelta), because -timedelta in isolation can overflow in cases
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	390 where date1 - timedelta does not. \code{\var{timedelta}.seconds}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	391 and \code{\var{timedelta}.microseconds} are ignored.
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	392
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	393 \item[(3)]
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	394 This is exact, and cannot overflow. timedelta.seconds and
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	395 timedelta.microseconds are 0, and date2 + timedelta == date1
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	396 after.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	397
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	398 \item[(4)]
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	399 In other words, \code{date1 < date2}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	400 if and only if \code{\var{date1}.toordinal() <
33992 a8de2195efd6 SF bug 1066438: datetime.replace method description error Tim Peters <tim.peters@gmail.com> parents: 31283 diff changeset	401 \var{date2}.toordinal()}.
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	402 In order to stop comparison from falling back to the default
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	403 scheme of comparing object addresses, date comparison
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	404 normally raises \exception{TypeError} if the other comparand
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	405 isn't also a \class{date} object. However, \code{NotImplemented}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	406 is returned instead if the other comparand has a
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	407 \method{timetuple} attribute. This hook gives other kinds of
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	408 date objects a chance at implementing mixed-type comparison.
27763 fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	409 If not, when a \class{date} object is
fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	410 compared to an object of a different type, \exception{TypeError} is
fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	411 raised unless the comparison is \code{==} or \code{!=}. The latter
fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	412 cases return \constant{False} or \constant{True}, respectively.
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	413
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	414 \end{description}
27365 00f294bf8299 date and datetime comparison: when we don't know how to Tim Peters <tim.peters@gmail.com> parents: 27351 diff changeset	415
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	416
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	417 Dates can be used as dictionary keys. In Boolean contexts, all
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	418 \class{date} objects are considered to be true.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	419
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	420 Instance methods:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	421
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	422 \begin{methoddesc}{replace}{year, month, day}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	423 Return a date with the same value, except for those members given
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	424 new values by whichever keyword arguments are specified. For
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	425 example, if \code{d == date(2002, 12, 31)}, then
33992 a8de2195efd6 SF bug 1066438: datetime.replace method description error Tim Peters <tim.peters@gmail.com> parents: 31283 diff changeset	426 \code{d.replace(day=26) == date(2002, 12, 26)}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	427 \end{methoddesc}
26773 0f1405ace437 Implemented .replace() methods for date, datetime, datetimetz, time and Tim Peters <tim.peters@gmail.com> parents: 26765 diff changeset	428
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	429 \begin{methoddesc}{timetuple}{}
30314 33dd12b2ebe6 Patch #792338: Correct documentation for timetuple return type. Martin v. Löwis <martin@v.loewis.de> parents: 29909 diff changeset	430 Return a \class{time.struct_time} such as returned by
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	431 \function{time.localtime()}. The hours, minutes and seconds are
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	432 0, and the DST flag is -1.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	433 \code{\var{d}.timetuple()} is equivalent to
30314 33dd12b2ebe6 Patch #792338: Correct documentation for timetuple return type. Martin v. Löwis <martin@v.loewis.de> parents: 29909 diff changeset	434 \code{time.struct_time((\var{d}.year, \var{d}.month, \var{d}.day,
33992 a8de2195efd6 SF bug 1066438: datetime.replace method description error Tim Peters <tim.peters@gmail.com> parents: 31283 diff changeset	435 0, 0, 0,
a8de2195efd6 SF bug 1066438: datetime.replace method description error Tim Peters <tim.peters@gmail.com> parents: 31283 diff changeset	436 \var{d}.weekday(),
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	437 \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
30314 33dd12b2ebe6 Patch #792338: Correct documentation for timetuple return type. Martin v. Löwis <martin@v.loewis.de> parents: 29909 diff changeset	438 -1))}
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	439 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	440
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	441 \begin{methoddesc}{toordinal}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	442 Return the proleptic Gregorian ordinal of the date, where January 1
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	443 of year 1 has ordinal 1. For any \class{date} object \var{d},
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	444 \code{date.fromordinal(\var{d}.toordinal()) == \var{d}}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	445 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	446
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	447 \begin{methoddesc}{weekday}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	448 Return the day of the week as an integer, where Monday is 0 and
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	449 Sunday is 6. For example, \code{date(2002, 12, 4).weekday() == 2}, a
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	450 Wednesday.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	451 See also \method{isoweekday()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	452 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	453
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	454 \begin{methoddesc}{isoweekday}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	455 Return the day of the week as an integer, where Monday is 1 and
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	456 Sunday is 7. For example, \code{date(2002, 12, 4).isoweekday() == 3}, a
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	457 Wednesday.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	458 See also \method{weekday()}, \method{isocalendar()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	459 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	460
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	461 \begin{methoddesc}{isocalendar}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	462 Return a 3-tuple, (ISO year, ISO week number, ISO weekday).
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	463
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	464 The ISO calendar is a widely used variant of the Gregorian calendar.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	465 See \url{http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	466 for a good explanation.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	467
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	468 The ISO year consists of 52 or 53 full weeks, and where a week starts
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	469 on a Monday and ends on a Sunday. The first week of an ISO year is
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	470 the first (Gregorian) calendar week of a year containing a Thursday.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	471 This is called week number 1, and the ISO year of that Thursday is
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	472 the same as its Gregorian year.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	473
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	474 For example, 2004 begins on a Thursday, so the first week of ISO
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	475 year 2004 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	476 2004, so that
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	477 \code{date(2003, 12, 29).isocalendar() == (2004, 1, 1)}
33992 a8de2195efd6 SF bug 1066438: datetime.replace method description error Tim Peters <tim.peters@gmail.com> parents: 31283 diff changeset	478 and
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	479 \code{date(2004, 1, 4).isocalendar() == (2004, 1, 7)}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	480 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	481
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	482 \begin{methoddesc}{isoformat}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	483 Return a string representing the date in ISO 8601 format,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	484 'YYYY-MM-DD'. For example,
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	485 \code{date(2002, 12, 4).isoformat() == '2002-12-04'}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	486 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	487
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	488 \begin{methoddesc}{__str__}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	489 For a date \var{d}, \code{str(\var{d})} is equivalent to
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	490 \code{\var{d}.isoformat()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	491 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	492
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	493 \begin{methoddesc}{ctime}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	494 Return a string representing the date, for example
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	495 date(2002, 12, 4).ctime() == 'Wed Dec 4 00:00:00 2002'.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	496 \code{\var{d}.ctime()} is equivalent to
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	497 \code{time.ctime(time.mktime(\var{d}.timetuple()))}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	498 on platforms where the native C \cfunction{ctime()} function
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	499 (which \function{time.ctime()} invokes, but which
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	500 \method{date.ctime()} does not invoke) conforms to the C standard.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	501 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	502
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	503 \begin{methoddesc}{strftime}{format}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	504 Return a string representing the date, controlled by an explicit
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	505 format string. Format codes referring to hours, minutes or seconds
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	506 will see 0 values.
37283 5203376f1589 Bug #1459103: add inter-section links for strftime section. Georg Brandl <georg@python.org> parents: 35996 diff changeset	507 See section~\ref{strftime-behavior} -- \method{strftime()} behavior.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	508 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	509
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	510
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	511 \subsection{\class{datetime} Objects \label{datetime-datetime}}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	512
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	513 A \class{datetime} object is a single object containing all the
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	514 information from a \class{date} object and a \class{time} object. Like a
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	515 \class{date} object, \class{datetime} assumes the current Gregorian
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	516 calendar extended in both directions; like a time object,
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	517 \class{datetime} assumes there are exactly 3600*24 seconds in every
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	518 day.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	519
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	520 Constructor:
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	521
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	522 \begin{classdesc}{datetime}{year, month, day\optional{,
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	523 hour\optional{, minute\optional{,
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	524 second\optional{, microsecond\optional{,
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	525 tzinfo}}}}}}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	526 The year, month and day arguments are required. \var{tzinfo} may
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	527 be \code{None}, or an instance of a \class{tzinfo} subclass. The
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	528 remaining arguments may be ints or longs, in the following ranges:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	529
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	530 \begin{itemize}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	531 \item \code{MINYEAR <= \var{year} <= MAXYEAR}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	532 \item \code{1 <= \var{month} <= 12}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	533 \item \code{1 <= \var{day} <= number of days in the given month and year}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	534 \item \code{0 <= \var{hour} < 24}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	535 \item \code{0 <= \var{minute} < 60}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	536 \item \code{0 <= \var{second} < 60}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	537 \item \code{0 <= \var{microsecond} < 1000000}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	538 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	539
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	540 If an argument outside those ranges is given,
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	541 \exception{ValueError} is raised.
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	542 \end{classdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	543
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	544 Other constructors, all class methods:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	545
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	546 \begin{methoddesc}{today}{}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	547 Return the current local datetime, with \member{tzinfo} \code{None}.
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	548 This is equivalent to
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	549 \code{datetime.fromtimestamp(time.time())}.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	550 See also \method{now()}, \method{fromtimestamp()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	551 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	552
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	553 \begin{methoddesc}{now}{\optional{tz}}
27350 22992fa51831 Reimplemented datetime.now() to be useful. Tim Peters <tim.peters@gmail.com> parents: 27339 diff changeset	554 Return the current local date and time. If optional argument
22992fa51831 Reimplemented datetime.now() to be useful. Tim Peters <tim.peters@gmail.com> parents: 27339 diff changeset	555 \var{tz} is \code{None} or not specified, this is like
22992fa51831 Reimplemented datetime.now() to be useful. Tim Peters <tim.peters@gmail.com> parents: 27339 diff changeset	556 \method{today()}, but, if possible, supplies more precision than can
22992fa51831 Reimplemented datetime.now() to be useful. Tim Peters <tim.peters@gmail.com> parents: 27339 diff changeset	557 be gotten from going through a \function{time.time()} timestamp (for
22992fa51831 Reimplemented datetime.now() to be useful. Tim Peters <tim.peters@gmail.com> parents: 27339 diff changeset	558 example, this may be possible on platforms supplying the C
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	559 \cfunction{gettimeofday()} function).
27350 22992fa51831 Reimplemented datetime.now() to be useful. Tim Peters <tim.peters@gmail.com> parents: 27339 diff changeset	560
22992fa51831 Reimplemented datetime.now() to be useful. Tim Peters <tim.peters@gmail.com> parents: 27339 diff changeset	561 Else \var{tz} must be an instance of a class \class{tzinfo} subclass,
27351 bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	562 and the current date and time are converted to \var{tz}'s time
27350 22992fa51831 Reimplemented datetime.now() to be useful. Tim Peters <tim.peters@gmail.com> parents: 27339 diff changeset	563 zone. In this case the result is equivalent to
27351 bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	564 \code{\var{tz}.fromutc(datetime.utcnow().replace(tzinfo=\var{tz}))}.
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	565 See also \method{today()}, \method{utcnow()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	566 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	567
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	568 \begin{methoddesc}{utcnow}{}
27350 22992fa51831 Reimplemented datetime.now() to be useful. Tim Peters <tim.peters@gmail.com> parents: 27339 diff changeset	569 Return the current UTC date and time, with \member{tzinfo} \code{None}.
27351 bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	570 This is like \method{now()}, but returns the current UTC date and time,
27350 22992fa51831 Reimplemented datetime.now() to be useful. Tim Peters <tim.peters@gmail.com> parents: 27339 diff changeset	571 as a naive \class{datetime} object.
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	572 See also \method{now()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	573 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	574
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	575 \begin{methoddesc}{fromtimestamp}{timestamp\optional{, tz}}
27351 bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	576 Return the local date and time corresponding to the \POSIX{}
bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	577 timestamp, such as is returned by \function{time.time()}.
bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	578 If optional argument \var{tz} is \code{None} or not specified, the
bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	579 timestamp is converted to the platform's local date and time, and
bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	580 the returned \class{datetime} object is naive.
bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	581
bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	582 Else \var{tz} must be an instance of a class \class{tzinfo} subclass,
bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	583 and the timestamp is converted to \var{tz}'s time zone. In this case
bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	584 the result is equivalent to
bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	585 \code{\var{tz}.fromutc(datetime.utcfromtimestamp(\var{timestamp}).replace(tzinfo=\var{tz}))}.
bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	586
bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	587 \method{fromtimestamp()} may raise \exception{ValueError}, if the
bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	588 timestamp is out of the range of values supported by the platform C
27376 840e9fed908a Fix markup Neal Norwitz <nnorwitz@gmail.com> parents: 27365 diff changeset	589 \cfunction{localtime()} or \cfunction{gmtime()} functions. It's common
27351 bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	590 for this to be restricted to years in 1970 through 2038.
27089 a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	591 Note that on non-POSIX systems that include leap seconds in their
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	592 notion of a timestamp, leap seconds are ignored by
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	593 \method{fromtimestamp()}, and then it's possible to have two timestamps
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	594 differing by a second that yield identical \class{datetime} objects.
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	595 See also \method{utcfromtimestamp()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	596 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	597
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	598 \begin{methoddesc}{utcfromtimestamp}{timestamp}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	599 Return the UTC \class{datetime} corresponding to the \POSIX{}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	600 timestamp, with \member{tzinfo} \code{None}.
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	601 This may raise \exception{ValueError}, if the
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	602 timestamp is out of the range of values supported by the platform
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	603 C \cfunction{gmtime()} function. It's common for this to be
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	604 restricted to years in 1970 through 2038.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	605 See also \method{fromtimestamp()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	606 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	607
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	608 \begin{methoddesc}{fromordinal}{ordinal}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	609 Return the \class{datetime} corresponding to the proleptic
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	610 Gregorian ordinal, where January 1 of year 1 has ordinal 1.
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	611 \exception{ValueError} is raised unless \code{1 <= ordinal <=
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	612 datetime.max.toordinal()}. The hour, minute, second and
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	613 microsecond of the result are all 0,
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	614 and \member{tzinfo} is \code{None}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	615 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	616
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	617 \begin{methoddesc}{combine}{date, time}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	618 Return a new \class{datetime} object whose date members are
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	619 equal to the given \class{date} object's, and whose time
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	620 and \member{tzinfo} members are equal to the given \class{time} object's.
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	621 For any \class{datetime} object \var{d}, \code{\var{d} ==
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	622 datetime.combine(\var{d}.date(), \var{d}.timetz())}. If date is a
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	623 \class{datetime} object, its time and \member{tzinfo} members are
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	624 ignored.
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	625 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	626
34416 563cbf4d6be4 Add strptime() constructor to datetime class. Thanks to Josh Spoerri for Skip Montanaro <skip@pobox.com> parents: 33992 diff changeset	627 \begin{methoddesc}{strptime}{date_string, format}
563cbf4d6be4 Add strptime() constructor to datetime class. Thanks to Josh Spoerri for Skip Montanaro <skip@pobox.com> parents: 33992 diff changeset	628 Return a \class{datetime} corresponding to \var{date_string}, parsed
563cbf4d6be4 Add strptime() constructor to datetime class. Thanks to Josh Spoerri for Skip Montanaro <skip@pobox.com> parents: 33992 diff changeset	629 according to \var{format}. This is equivalent to
563cbf4d6be4 Add strptime() constructor to datetime class. Thanks to Josh Spoerri for Skip Montanaro <skip@pobox.com> parents: 33992 diff changeset	630 \code{datetime(*(time.strptime(date_string,
563cbf4d6be4 Add strptime() constructor to datetime class. Thanks to Josh Spoerri for Skip Montanaro <skip@pobox.com> parents: 33992 diff changeset	631 format)[0:6]))}. \exception{ValueError} is raised if the date_string and
563cbf4d6be4 Add strptime() constructor to datetime class. Thanks to Josh Spoerri for Skip Montanaro <skip@pobox.com> parents: 33992 diff changeset	632 format can't be parsed by \function{time.strptime()} or if it returns a
563cbf4d6be4 Add strptime() constructor to datetime class. Thanks to Josh Spoerri for Skip Montanaro <skip@pobox.com> parents: 33992 diff changeset	633 value which isn't a time tuple.
34420 269a2c14bc57 Gave the new datetime.strptime() a versionadded blurb. Tim Peters <tim.peters@gmail.com> parents: 34416 diff changeset	634
269a2c14bc57 Gave the new datetime.strptime() a versionadded blurb. Tim Peters <tim.peters@gmail.com> parents: 34416 diff changeset	635 \versionadded{2.5}
34416 563cbf4d6be4 Add strptime() constructor to datetime class. Thanks to Josh Spoerri for Skip Montanaro <skip@pobox.com> parents: 33992 diff changeset	636 \end{methoddesc}
563cbf4d6be4 Add strptime() constructor to datetime class. Thanks to Josh Spoerri for Skip Montanaro <skip@pobox.com> parents: 33992 diff changeset	637
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	638 Class attributes:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	639
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	640 \begin{memberdesc}{min}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	641 The earliest representable \class{datetime},
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	642 \code{datetime(MINYEAR, 1, 1, tzinfo=None)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	643 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	644
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	645 \begin{memberdesc}{max}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	646 The latest representable \class{datetime},
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	647 \code{datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	648 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	649
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	650 \begin{memberdesc}{resolution}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	651 The smallest possible difference between non-equal \class{datetime}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	652 objects, \code{timedelta(microseconds=1)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	653 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	654
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	655 Instance attributes (read-only):
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	656
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	657 \begin{memberdesc}{year}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	658 Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	659 \end{memberdesc}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	660
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	661 \begin{memberdesc}{month}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	662 Between 1 and 12 inclusive.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	663 \end{memberdesc}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	664
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	665 \begin{memberdesc}{day}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	666 Between 1 and the number of days in the given month of the given
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	667 year.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	668 \end{memberdesc}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	669
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	670 \begin{memberdesc}{hour}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	671 In \code{range(24)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	672 \end{memberdesc}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	673
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	674 \begin{memberdesc}{minute}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	675 In \code{range(60)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	676 \end{memberdesc}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	677
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	678 \begin{memberdesc}{second}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	679 In \code{range(60)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	680 \end{memberdesc}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	681
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	682 \begin{memberdesc}{microsecond}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	683 In \code{range(1000000)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	684 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	685
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	686 \begin{memberdesc}{tzinfo}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	687 The object passed as the \var{tzinfo} argument to the
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	688 \class{datetime} constructor, or \code{None} if none was passed.
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	689 \end{memberdesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	690
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	691 Supported operations:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	692
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	693 \begin{tableii}{c\|l}{code}{Operation}{Result}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	694 \lineii{\var{datetime2} = \var{datetime1} + \var{timedelta}}{(1)}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	695
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	696 \lineii{\var{datetime2} = \var{datetime1} - \var{timedelta}}{(2)}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	697
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	698 \lineii{\var{timedelta} = \var{datetime1} - \var{datetime2}}{(3)}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	699
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	700 \lineii{\var{datetime1} < \var{datetime2}}
33992 a8de2195efd6 SF bug 1066438: datetime.replace method description error Tim Peters <tim.peters@gmail.com> parents: 31283 diff changeset	701 {Compares \class{datetime} to \class{datetime}.
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	702 (4)}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	703
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	704 \end{tableii}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	705
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	706 \begin{description}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	707
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	708 \item[(1)]
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	709
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	710 datetime2 is a duration of timedelta removed from datetime1, moving
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	711 forward in time if \code{\var{timedelta}.days} > 0, or backward if
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	712 \code{\var{timedelta}.days} < 0. The result has the same \member{tzinfo} member
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	713 as the input datetime, and datetime2 - datetime1 == timedelta after.
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	714 \exception{OverflowError} is raised if datetime2.year would be
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	715 smaller than \constant{MINYEAR} or larger than \constant{MAXYEAR}.
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	716 Note that no time zone adjustments are done even if the input is an
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	717 aware object.
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	718
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	719 \item[(2)]
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	720 Computes the datetime2 such that datetime2 + timedelta == datetime1.
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	721 As for addition, the result has the same \member{tzinfo} member
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	722 as the input datetime, and no time zone adjustments are done even
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	723 if the input is aware.
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	724 This isn't quite equivalent to datetime1 + (-timedelta), because
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	725 -timedelta in isolation can overflow in cases where
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	726 datetime1 - timedelta does not.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	727
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	728 \item[(3)]
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	729 Subtraction of a \class{datetime} from a
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	730 \class{datetime} is defined only if both
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	731 operands are naive, or if both are aware. If one is aware and the
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	732 other is naive, \exception{TypeError} is raised.
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	733
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	734 If both are naive, or both are aware and have the same \member{tzinfo}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	735 member, the \member{tzinfo} members are ignored, and the result is
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	736 a \class{timedelta} object \var{t} such that
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	737 \code{\var{datetime2} + \var{t} == \var{datetime1}}. No time zone
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	738 adjustments are done in this case.
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	739
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	740 If both are aware and have different \member{tzinfo} members,
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	741 \code{a-b} acts as if \var{a} and \var{b} were first converted to
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	742 naive UTC datetimes first. The result is
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	743 \code{(\var{a}.replace(tzinfo=None) - \var{a}.utcoffset()) -
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	744 (\var{b}.replace(tzinfo=None) - \var{b}.utcoffset())}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	745 except that the implementation never overflows.
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	746
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	747 \item[(4)]
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	748
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	749 \var{datetime1} is considered less than \var{datetime2}
33992 a8de2195efd6 SF bug 1066438: datetime.replace method description error Tim Peters <tim.peters@gmail.com> parents: 31283 diff changeset	750 when \var{datetime1} precedes \var{datetime2} in time.
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	751
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	752 If one comparand is naive and
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	753 the other is aware, \exception{TypeError} is raised. If both
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	754 comparands are aware, and have the same \member{tzinfo} member,
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	755 the common \member{tzinfo} member is ignored and the base datetimes
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	756 are compared. If both comparands are aware and have different
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	757 \member{tzinfo} members, the comparands are first adjusted by
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	758 subtracting their UTC offsets (obtained from \code{self.utcoffset()}).
27365 00f294bf8299 date and datetime comparison: when we don't know how to Tim Peters <tim.peters@gmail.com> parents: 27351 diff changeset	759 \note{In order to stop comparison from falling back to the default
00f294bf8299 date and datetime comparison: when we don't know how to Tim Peters <tim.peters@gmail.com> parents: 27351 diff changeset	760 scheme of comparing object addresses, datetime comparison
00f294bf8299 date and datetime comparison: when we don't know how to Tim Peters <tim.peters@gmail.com> parents: 27351 diff changeset	761 normally raises \exception{TypeError} if the other comparand
00f294bf8299 date and datetime comparison: when we don't know how to Tim Peters <tim.peters@gmail.com> parents: 27351 diff changeset	762 isn't also a \class{datetime} object. However,
00f294bf8299 date and datetime comparison: when we don't know how to Tim Peters <tim.peters@gmail.com> parents: 27351 diff changeset	763 \code{NotImplemented} is returned instead if the other comparand
00f294bf8299 date and datetime comparison: when we don't know how to Tim Peters <tim.peters@gmail.com> parents: 27351 diff changeset	764 has a \method{timetuple} attribute. This hook gives other
00f294bf8299 date and datetime comparison: when we don't know how to Tim Peters <tim.peters@gmail.com> parents: 27351 diff changeset	765 kinds of date objects a chance at implementing mixed-type
27763 fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	766 comparison. If not, when a \class{datetime} object is
fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	767 compared to an object of a different type, \exception{TypeError}
fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	768 is raised unless the comparison is \code{==} or \code{!=}. The
fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	769 latter cases return \constant{False} or \constant{True},
fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	770 respectively.}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	771
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	772 \end{description}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	773
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	774 \class{datetime} objects can be used as dictionary keys. In Boolean
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	775 contexts, all \class{datetime} objects are considered to be true.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	776
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	777
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	778 Instance methods:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	779
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	780 \begin{methoddesc}{date}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	781 Return \class{date} object with same year, month and day.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	782 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	783
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	784 \begin{methoddesc}{time}{}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	785 Return \class{time} object with same hour, minute, second and microsecond.
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	786 \member{tzinfo} is \code{None}. See also method \method{timetz()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	787 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	788
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	789 \begin{methoddesc}{timetz}{}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	790 Return \class{time} object with same hour, minute, second, microsecond,
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	791 and tzinfo members. See also method \method{time()}.
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	792 \end{methoddesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	793
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	794 \begin{methoddesc}{replace}{\optional{year\optional{, month\optional{,
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	795 day\optional{, hour\optional{, minute\optional{,
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	796 second\optional{, microsecond\optional{,
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	797 tzinfo}}}}}}}}}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	798 Return a datetime with the same members, except for those members given
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	799 new values by whichever keyword arguments are specified. Note that
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	800 \code{tzinfo=None} can be specified to create a naive datetime from
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	801 an aware datetime with no conversion of date and time members.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	802 \end{methoddesc}
26773 0f1405ace437 Implemented .replace() methods for date, datetime, datetimetz, time and Tim Peters <tim.peters@gmail.com> parents: 26765 diff changeset	803
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	804 \begin{methoddesc}{astimezone}{tz}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	805 Return a \class{datetime} object with new \member{tzinfo} member
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	806 \var{tz}, adjusting the date and time members so the result is the
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	807 same UTC time as \var{self}, but in \var{tz}'s local time.
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	808
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	809 \var{tz} must be an instance of a \class{tzinfo} subclass, and its
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	810 \method{utcoffset()} and \method{dst()} methods must not return
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	811 \code{None}. \var{self} must be aware (\code{\var{self}.tzinfo} must
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	812 not be \code{None}, and \code{\var{self}.utcoffset()} must not return
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	813 \code{None}).
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	814
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	815 If \code{\var{self}.tzinfo} is \var{tz},
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	816 \code{\var{self}.astimezone(\var{tz})} is equal to \var{self}: no
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	817 adjustment of date or time members is performed.
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	818 Else the result is local time in time zone \var{tz}, representing the
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	819 same UTC time as \var{self}: after \code{\var{astz} =
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	820 \var{dt}.astimezone(\var{tz})},
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	821 \code{\var{astz} - \var{astz}.utcoffset()} will usually have the same
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	822 date and time members as \code{\var{dt} - \var{dt}.utcoffset()}.
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	823 The discussion of class \class{tzinfo} explains the cases at Daylight
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	824 Saving Time transition boundaries where this cannot be achieved (an issue
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	825 only if \var{tz} models both standard and daylight time).
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	826
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	827 If you merely want to attach a time zone object \var{tz} to a
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	828 datetime \var{dt} without adjustment of date and time members,
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	829 use \code{\var{dt}.replace(tzinfo=\var{tz})}. If
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	830 you merely want to remove the time zone object from an aware datetime
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	831 \var{dt} without conversion of date and time members, use
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	832 \code{\var{dt}.replace(tzinfo=None)}.
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	833
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	834 Note that the default \method{tzinfo.fromutc()} method can be overridden
30349 d6153603472e SF bug 799367: grammar error Raymond Hettinger <python@rcn.com> parents: 30314 diff changeset	835 in a \class{tzinfo} subclass to affect the result returned by
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	836 \method{astimezone()}. Ignoring error cases, \method{astimezone()}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	837 acts like:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	838
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	839 \begin{verbatim}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	840 def astimezone(self, tz):
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	841 if self.tzinfo is tz:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	842 return self
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	843 # Convert self to UTC, and attach the new time zone object.
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	844 utc = (self - self.utcoffset()).replace(tzinfo=tz)
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	845 # Convert from UTC to tz's local time.
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	846 return tz.fromutc(utc)
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	847 \end{verbatim}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	848 \end{methoddesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	849
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	850 \begin{methoddesc}{utcoffset}{}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	851 If \member{tzinfo} is \code{None}, returns \code{None}, else
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	852 returns \code{\var{self}.tzinfo.utcoffset(\var{self})}, and
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	853 raises an exception if the latter doesn't return \code{None}, or
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	854 a \class{timedelta} object representing a whole number of minutes
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	855 with magnitude less than one day.
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	856 \end{methoddesc}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	857
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	858 \begin{methoddesc}{dst}{}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	859 If \member{tzinfo} is \code{None}, returns \code{None}, else
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	860 returns \code{\var{self}.tzinfo.dst(\var{self})}, and
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	861 raises an exception if the latter doesn't return \code{None}, or
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	862 a \class{timedelta} object representing a whole number of minutes
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	863 with magnitude less than one day.
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	864 \end{methoddesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	865
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	866 \begin{methoddesc}{tzname}{}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	867 If \member{tzinfo} is \code{None}, returns \code{None}, else
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	868 returns \code{\var{self}.tzinfo.tzname(\var{self})},
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	869 raises an exception if the latter doesn't return \code{None} or
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	870 a string object,
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	871 \end{methoddesc}
26792 816b8ddccfe1 Implemented datetime.astimezone() and datetimetz.astimezone(). Tim Peters <tim.peters@gmail.com> parents: 26787 diff changeset	872
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	873 \begin{methoddesc}{timetuple}{}
30314 33dd12b2ebe6 Patch #792338: Correct documentation for timetuple return type. Martin v. Löwis <martin@v.loewis.de> parents: 29909 diff changeset	874 Return a \class{time.struct_time} such as returned by
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	875 \function{time.localtime()}.
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	876 \code{\var{d}.timetuple()} is equivalent to
30314 33dd12b2ebe6 Patch #792338: Correct documentation for timetuple return type. Martin v. Löwis <martin@v.loewis.de> parents: 29909 diff changeset	877 \code{time.struct_time((\var{d}.year, \var{d}.month, \var{d}.day,
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	878 \var{d}.hour, \var{d}.minute, \var{d}.second,
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	879 \var{d}.weekday(),
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	880 \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
30314 33dd12b2ebe6 Patch #792338: Correct documentation for timetuple return type. Martin v. Löwis <martin@v.loewis.de> parents: 29909 diff changeset	881 dst))}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	882 The \member{tm_isdst} flag of the result is set according to
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	883 the \method{dst()} method: \member{tzinfo} is \code{None} or
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	884 \method{dst()} returns \code{None},
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	885 \member{tm_isdst} is set to \code{-1}; else if \method{dst()} returns
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	886 a non-zero value, \member{tm_isdst} is set to \code{1};
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	887 else \code{tm_isdst} is set to \code{0}.
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	888 \end{methoddesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	889
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	890 \begin{methoddesc}{utctimetuple}{}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	891 If \class{datetime} instance \var{d} is naive, this is the same as
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	892 \code{\var{d}.timetuple()} except that \member{tm_isdst} is forced to 0
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	893 regardless of what \code{d.dst()} returns. DST is never in effect
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	894 for a UTC time.
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	895
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	896 If \var{d} is aware, \var{d} is normalized to UTC time, by subtracting
30314 33dd12b2ebe6 Patch #792338: Correct documentation for timetuple return type. Martin v. Löwis <martin@v.loewis.de> parents: 29909 diff changeset	897 \code{\var{d}.utcoffset()}, and a \class{time.struct_time} for the
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	898 normalized time is returned. \member{tm_isdst} is forced to 0.
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	899 Note that the result's \member{tm_year} member may be
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	900 \constant{MINYEAR}-1 or \constant{MAXYEAR}+1, if \var{d}.year was
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	901 \code{MINYEAR} or \code{MAXYEAR} and UTC adjustment spills over a
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	902 year boundary.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	903 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	904
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	905 \begin{methoddesc}{toordinal}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	906 Return the proleptic Gregorian ordinal of the date. The same as
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	907 \code{self.date().toordinal()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	908 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	909
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	910 \begin{methoddesc}{weekday}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	911 Return the day of the week as an integer, where Monday is 0 and
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	912 Sunday is 6. The same as \code{self.date().weekday()}.
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	913 See also \method{isoweekday()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	914 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	915
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	916 \begin{methoddesc}{isoweekday}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	917 Return the day of the week as an integer, where Monday is 1 and
29063 ab7dc538f6f7 Fix missing parenthesis. Raymond Hettinger <python@rcn.com> parents: 27763 diff changeset	918 Sunday is 7. The same as \code{self.date().isoweekday()}.
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	919 See also \method{weekday()}, \method{isocalendar()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	920 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	921
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	922 \begin{methoddesc}{isocalendar}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	923 Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	924 same as \code{self.date().isocalendar()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	925 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	926
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	927 \begin{methoddesc}{isoformat}{\optional{sep}}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	928 Return a string representing the date and time in ISO 8601 format,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	929 YYYY-MM-DDTHH:MM:SS.mmmmmm
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	930 or, if \member{microsecond} is 0,
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	931 YYYY-MM-DDTHH:MM:SS
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	932
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	933 If \method{utcoffset()} does not return \code{None}, a 6-character
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	934 string is appended, giving the UTC offset in (signed) hours and
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	935 minutes:
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	936 YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	937 or, if \member{microsecond} is 0
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	938 YYYY-MM-DDTHH:MM:SS+HH:MM
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	939
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	940 The optional argument \var{sep} (default \code{'T'}) is a
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	941 one-character separator, placed between the date and time portions
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	942 of the result. For example,
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	943
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	944 \begin{verbatim}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	945 >>> from datetime import tzinfo, timedelta, datetime
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	946 >>> class TZ(tzinfo):
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	947 ... def utcoffset(self, dt): return timedelta(minutes=-399)
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	948 ...
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	949 >>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	950 '2002-12-25 00:00:00-06:39'
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	951 \end{verbatim}
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	952 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	953
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	954 \begin{methoddesc}{__str__}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	955 For a \class{datetime} instance \var{d}, \code{str(\var{d})} is
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	956 equivalent to \code{\var{d}.isoformat(' ')}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	957 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	958
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	959 \begin{methoddesc}{ctime}{}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	960 Return a string representing the date and time, for example
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	961 \code{datetime(2002, 12, 4, 20, 30, 40).ctime() ==
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	962 'Wed Dec 4 20:30:40 2002'}.
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	963 \code{d.ctime()} is equivalent to
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	964 \code{time.ctime(time.mktime(d.timetuple()))} on platforms where
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	965 the native C \cfunction{ctime()} function (which
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	966 \function{time.ctime()} invokes, but which
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	967 \method{datetime.ctime()} does not invoke) conforms to the C
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	968 standard.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	969 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	970
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	971 \begin{methoddesc}{strftime}{format}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	972 Return a string representing the date and time, controlled by an
37283 5203376f1589 Bug #1459103: add inter-section links for strftime section. Georg Brandl <georg@python.org> parents: 35996 diff changeset	973 explicit format string. See section~\ref{strftime-behavior} --
5203376f1589 Bug #1459103: add inter-section links for strftime section. Georg Brandl <georg@python.org> parents: 35996 diff changeset	974 \method{strftime()} behavior.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	975 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	976
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	977
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	978 \subsection{\class{time} Objects \label{datetime-time}}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	979
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	980 A time object represents a (local) time of day, independent of any
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	981 particular day, and subject to adjustment via a \class{tzinfo} object.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	982
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	983 \begin{classdesc}{time}{hour\optional{, minute\optional{, second\optional{,
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	984 microsecond\optional{, tzinfo}}}}}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	985 All arguments are optional. \var{tzinfo} may be \code{None}, or
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	986 an instance of a \class{tzinfo} subclass. The remaining arguments
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	987 may be ints or longs, in the following ranges:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	988
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	989 \begin{itemize}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	990 \item \code{0 <= \var{hour} < 24}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	991 \item \code{0 <= \var{minute} < 60}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	992 \item \code{0 <= \var{second} < 60}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	993 \item \code{0 <= \var{microsecond} < 1000000}.
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	994 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	995
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	996 If an argument outside those ranges is given,
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	997 \exception{ValueError} is raised. All default to \code{0} except
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	998 \var{tzinfo}, which defaults to \constant{None}.
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	999 \end{classdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1000
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1001 Class attributes:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1002
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1003 \begin{memberdesc}{min}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1004 The earliest representable \class{time}, \code{time(0, 0, 0, 0)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1005 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1006
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1007 \begin{memberdesc}{max}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1008 The latest representable \class{time}, \code{time(23, 59, 59, 999999)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1009 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1010
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1011 \begin{memberdesc}{resolution}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1012 The smallest possible difference between non-equal \class{time}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1013 objects, \code{timedelta(microseconds=1)}, although note that
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1014 arithmetic on \class{time} objects is not supported.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1015 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1016
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1017 Instance attributes (read-only):
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1018
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1019 \begin{memberdesc}{hour}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1020 In \code{range(24)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1021 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1022
26876 35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1023 \begin{memberdesc}{minute}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1024 In \code{range(60)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1025 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1026
26876 35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1027 \begin{memberdesc}{second}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1028 In \code{range(60)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1029 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1030
26876 35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1031 \begin{memberdesc}{microsecond}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1032 In \code{range(1000000)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1033 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1034
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1035 \begin{memberdesc}{tzinfo}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1036 The object passed as the tzinfo argument to the \class{time}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1037 constructor, or \code{None} if none was passed.
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1038 \end{memberdesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1039
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1040 Supported operations:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1041
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1042 \begin{itemize}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1043 \item
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1044 comparison of \class{time} to \class{time},
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1045 where \var{a} is considered less than \var{b} when \var{a} precedes
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1046 \var{b} in time. If one comparand is naive and the other is aware,
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1047 \exception{TypeError} is raised. If both comparands are aware, and
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1048 have the same \member{tzinfo} member, the common \member{tzinfo}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1049 member is ignored and the base times are compared. If both
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1050 comparands are aware and have different \member{tzinfo} members,
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1051 the comparands are first adjusted by subtracting their UTC offsets
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1052 (obtained from \code{self.utcoffset()}).
27763 fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	1053 In order to stop mixed-type comparisons from falling back to the
fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	1054 default comparison by object address, when a \class{time} object is
fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	1055 compared to an object of a different type, \exception{TypeError} is
fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	1056 raised unless the comparison is \code{==} or \code{!=}. The latter
fc88174c0c0a Comparison for timedelta, time, date and datetime objects: __eq__ and Tim Peters <tim.peters@gmail.com> parents: 27704 diff changeset	1057 cases return \constant{False} or \constant{True}, respectively.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1058
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1059 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1060 hash, use as dict key
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1061
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1062 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1063 efficient pickling
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1064
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1065 \item
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1066 in Boolean contexts, a \class{time} object is considered to be
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1067 true if and only if, after converting it to minutes and
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1068 subtracting \method{utcoffset()} (or \code{0} if that's
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1069 \code{None}), the result is non-zero.
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1070 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1071
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1072 Instance methods:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1073
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1074 \begin{methoddesc}{replace}{\optional{hour\optional{, minute\optional{,
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1075 second\optional{, microsecond\optional{,
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1076 tzinfo}}}}}}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1077 Return a \class{time} with the same value, except for those members given
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1078 new values by whichever keyword arguments are specified. Note that
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1079 \code{tzinfo=None} can be specified to create a naive \class{time} from
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1080 an aware \class{time}, without conversion of the time members.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1081 \end{methoddesc}
26773 0f1405ace437 Implemented .replace() methods for date, datetime, datetimetz, time and Tim Peters <tim.peters@gmail.com> parents: 26765 diff changeset	1082
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1083 \begin{methoddesc}{isoformat}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1084 Return a string representing the time in ISO 8601 format,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1085 HH:MM:SS.mmmmmm
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1086 or, if self.microsecond is 0,
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1087 HH:MM:SS
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1088 If \method{utcoffset()} does not return \code{None}, a 6-character
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1089 string is appended, giving the UTC offset in (signed) hours and
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1090 minutes:
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1091 HH:MM:SS.mmmmmm+HH:MM
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1092 or, if self.microsecond is 0,
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1093 HH:MM:SS+HH:MM
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1094 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1095
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1096 \begin{methoddesc}{__str__}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1097 For a time \var{t}, \code{str(\var{t})} is equivalent to
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1098 \code{\var{t}.isoformat()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1099 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1100
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1101 \begin{methoddesc}{strftime}{format}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1102 Return a string representing the time, controlled by an explicit
37283 5203376f1589 Bug #1459103: add inter-section links for strftime section. Georg Brandl <georg@python.org> parents: 35996 diff changeset	1103 format string. See section~\ref{strftime-behavior} --
5203376f1589 Bug #1459103: add inter-section links for strftime section. Georg Brandl <georg@python.org> parents: 35996 diff changeset	1104 \method{strftime()} behavior.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1105 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1106
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1107 \begin{methoddesc}{utcoffset}{}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1108 If \member{tzinfo} is \code{None}, returns \code{None}, else
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1109 returns \code{\var{self}.tzinfo.utcoffset(None)}, and
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1110 raises an exception if the latter doesn't return \code{None} or
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1111 a \class{timedelta} object representing a whole number of minutes
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1112 with magnitude less than one day.
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1113 \end{methoddesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1114
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1115 \begin{methoddesc}{dst}{}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1116 If \member{tzinfo} is \code{None}, returns \code{None}, else
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1117 returns \code{\var{self}.tzinfo.dst(None)}, and
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1118 raises an exception if the latter doesn't return \code{None}, or
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1119 a \class{timedelta} object representing a whole number of minutes
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1120 with magnitude less than one day.
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1121 \end{methoddesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1122
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1123 \begin{methoddesc}{tzname}{}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1124 If \member{tzinfo} is \code{None}, returns \code{None}, else
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1125 returns \code{\var{self}.tzinfo.tzname(None)}, or
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1126 raises an exception if the latter doesn't return \code{None} or
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1127 a string object.
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1128 \end{methoddesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1129
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1130
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	1131 \subsection{\class{tzinfo} Objects \label{datetime-tzinfo}}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1132
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1133 \class{tzinfo} is an abstract base clase, meaning that this class
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1134 should not be instantiated directly. You need to derive a concrete
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1135 subclass, and (at least) supply implementations of the standard
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1136 \class{tzinfo} methods needed by the \class{datetime} methods you
26876 35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1137 use. The \module{datetime} module does not supply any concrete
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1138 subclasses of \class{tzinfo}.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1139
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1140 An instance of (a concrete subclass of) \class{tzinfo} can be passed
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1141 to the constructors for \class{datetime} and \class{time} objects.
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1142 The latter objects view their members as being in local time, and the
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1143 \class{tzinfo} object supports methods revealing offset of local time
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1144 from UTC, the name of the time zone, and DST offset, all relative to a
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1145 date or time object passed to them.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1146
26876 35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1147 Special requirement for pickling: A \class{tzinfo} subclass must have an
26786 7c5196f01524 Added note about technical pickle limitation on tzinfo instances. Tim Peters <tim.peters@gmail.com> parents: 26785 diff changeset	1148 \method{__init__} method that can be called with no arguments, else it
7c5196f01524 Added note about technical pickle limitation on tzinfo instances. Tim Peters <tim.peters@gmail.com> parents: 26785 diff changeset	1149 can be pickled but possibly not unpickled again. This is a technical
7c5196f01524 Added note about technical pickle limitation on tzinfo instances. Tim Peters <tim.peters@gmail.com> parents: 26785 diff changeset	1150 requirement that may be relaxed in the future.
7c5196f01524 Added note about technical pickle limitation on tzinfo instances. Tim Peters <tim.peters@gmail.com> parents: 26785 diff changeset	1151
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1152 A concrete subclass of \class{tzinfo} may need to implement the
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1153 following methods. Exactly which methods are needed depends on the
26876 35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1154 uses made of aware \module{datetime} objects. If in doubt, simply
35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1155 implement all of them.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1156
26876 35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1157 \begin{methoddesc}{utcoffset}{self, dt}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1158 Return offset of local time from UTC, in minutes east of UTC. If
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1159 local time is west of UTC, this should be negative. Note that this
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1160 is intended to be the total offset from UTC; for example, if a
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1161 \class{tzinfo} object represents both time zone and DST adjustments,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1162 \method{utcoffset()} should return their sum. If the UTC offset
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1163 isn't known, return \code{None}. Else the value returned must be
27037 99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	1164 a \class{timedelta} object specifying a whole number of minutes in the
99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	1165 range -1439 to 1439 inclusive (1440 = 24*60; the magnitude of the offset
99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	1166 must be less than one day). Most implementations of
99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	1167 \method{utcoffset()} will probably look like one of these two:
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1168
26876 35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1169 \begin{verbatim}
27008 4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	1170 return CONSTANT # fixed-offset class
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1171 return CONSTANT + self.dst(dt) # daylight-aware class
26924 31adea49a558 Minor markup and spelling repair. Guido van Rossum <guido@python.org> parents: 26881 diff changeset	1172 \end{verbatim}
27034 dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	1173
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	1174 If \method{utcoffset()} does not return \code{None},
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	1175 \method{dst()} should not return \code{None} either.
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1176
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1177 The default implementation of \method{utcoffset()} raises
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1178 \exception{NotImplementedError}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1179 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1180
26876 35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1181 \begin{methoddesc}{dst}{self, dt}
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1182 Return the daylight saving time (DST) adjustment, in minutes east of
27330 6cda7c612154 SF bug 671779: Error in tzinfo.dst() docs Tim Peters <tim.peters@gmail.com> parents: 27315 diff changeset	1183 UTC, or \code{None} if DST information isn't known. Return
6cda7c612154 SF bug 671779: Error in tzinfo.dst() docs Tim Peters <tim.peters@gmail.com> parents: 27315 diff changeset	1184 \code{timedelta(0)} if DST is not in effect.
27037 99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	1185 If DST is in effect, return the offset as a
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1186 \class{timedelta} object (see \method{utcoffset()} for details).
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1187 Note that DST offset, if applicable, has
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1188 already been added to the UTC offset returned by
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1189 \method{utcoffset()}, so there's no need to consult \method{dst()}
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1190 unless you're interested in obtaining DST info separately. For
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1191 example, \method{datetime.timetuple()} calls its \member{tzinfo}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1192 member's \method{dst()} method to determine how the
27008 4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	1193 \member{tm_isdst} flag should be set, and
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1194 \method{tzinfo.fromutc()} calls \method{dst()} to account for
27008 4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	1195 DST changes when crossing time zones.
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	1196
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	1197 An instance \var{tz} of a \class{tzinfo} subclass that models both
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	1198 standard and daylight times must be consistent in this sense:
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	1199
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1200 \code{\var{tz}.utcoffset(\var{dt}) - \var{tz}.dst(\var{dt})}
27008 4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	1201
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1202 must return the same result for every \class{datetime} \var{dt}
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1203 with \code{\var{dt}.tzinfo == \var{tz}} For sane \class{tzinfo}
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1204 subclasses, this expression yields the time zone's "standard offset",
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1205 which should not depend on the date or the time, but only on geographic
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1206 location. The implementation of \method{datetime.astimezone()} relies
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1207 on this, but cannot detect violations; it's the programmer's
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1208 responsibility to ensure it. If a \class{tzinfo} subclass cannot
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1209 guarantee this, it may be able to override the default implementation
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1210 of \method{tzinfo.fromutc()} to work correctly with \method{astimezone()}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1211 regardless.
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1212
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1213 Most implementations of \method{dst()} will probably look like one
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1214 of these two:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1215
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1216 \begin{verbatim}
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1217 def dst(self):
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1218 # a fixed-offset class: doesn't account for DST
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1219 return timedelta(0)
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1220 \end{verbatim}
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1221
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1222 or
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1223
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1224 \begin{verbatim}
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1225 def dst(self):
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1226 # Code to set dston and dstoff to the time zone's DST
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1227 # transition times based on the input dt.year, and expressed
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1228 # in standard local time. Then
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1229
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1230 if dston <= dt.replace(tzinfo=None) < dstoff:
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1231 return timedelta(hours=1)
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1232 else:
d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1233 return timedelta(0)
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1234 \end{verbatim}
27008 4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	1235
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1236 The default implementation of \method{dst()} raises
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1237 \exception{NotImplementedError}.
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1238 \end{methoddesc}
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1239
27034 dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	1240 \begin{methoddesc}{tzname}{self, dt}
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1241 Return the time zone name corresponding to the \class{datetime}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1242 object \var{dt}, as a string.
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1243 Nothing about string names is defined by the
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1244 \module{datetime} module, and there's no requirement that it mean
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1245 anything in particular. For example, "GMT", "UTC", "-500", "-5:00",
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1246 "EDT", "US/Eastern", "America/New York" are all valid replies. Return
27034 dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	1247 \code{None} if a string name isn't known. Note that this is a method
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1248 rather than a fixed string primarily because some \class{tzinfo}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1249 subclasses will wish to return different names depending on the specific
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1250 value of \var{dt} passed, especially if the \class{tzinfo} class is
27034 dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	1251 accounting for daylight time.
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	1252
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1253 The default implementation of \method{tzname()} raises
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1254 \exception{NotImplementedError}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1255 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1256
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1257 These methods are called by a \class{datetime} or \class{time} object,
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1258 in response to their methods of the same names. A \class{datetime}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1259 object passes itself as the argument, and a \class{time} object passes
26876 35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1260 \code{None} as the argument. A \class{tzinfo} subclass's methods should
35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1261 therefore be prepared to accept a \var{dt} argument of \code{None}, or of
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1262 class \class{datetime}.
26876 35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1263
35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1264 When \code{None} is passed, it's up to the class designer to decide the
35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1265 best response. For example, returning \code{None} is appropriate if the
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1266 class wishes to say that time objects don't participate in the
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1267 \class{tzinfo} protocols. It may be more useful for \code{utcoffset(None)}
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1268 to return the standard UTC offset, as there is no other convention for
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1269 discovering the standard offset.
26876 35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1270
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1271 When a \class{datetime} object is passed in response to a
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1272 \class{datetime} method, \code{dt.tzinfo} is the same object as
26876 35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1273 \var{self}. \class{tzinfo} methods can rely on this, unless
35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1274 user code calls \class{tzinfo} methods directly. The intent is that
35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1275 the \class{tzinfo} methods interpret \var{dt} as being in local time,
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1276 and not need worry about objects in other timezones.
26876 35468ad5022a A step on the way to making tzinfo classes writable by mortals: get rid Tim Peters <tim.peters@gmail.com> parents: 26872 diff changeset	1277
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1278 There is one more \class{tzinfo} method that a subclass may wish to
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1279 override:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1280
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1281 \begin{methoddesc}{fromutc}{self, dt}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1282 This is called from the default \class{datetime.astimezone()}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1283 implementation. When called from that, \code{\var{dt}.tzinfo} is
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1284 \var{self}, and \var{dt}'s date and time members are to be viewed as
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1285 expressing a UTC time. The purpose of \method{fromutc()} is to
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1286 adjust the date and time members, returning an equivalent datetime in
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1287 \var{self}'s local time.
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1288
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1289 Most \class{tzinfo} subclasses should be able to inherit the default
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1290 \method{fromutc()} implementation without problems. It's strong enough
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1291 to handle fixed-offset time zones, and time zones accounting for both
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1292 standard and daylight time, and the latter even if the DST transition
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1293 times differ in different years. An example of a time zone the default
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1294 \method{fromutc()} implementation may not handle correctly in all cases
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1295 is one where the standard offset (from UTC) depends on the specific date
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1296 and time passed, which can happen for political reasons.
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1297 The default implementations of \method{astimezone()} and
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1298 \method{fromutc()} may not produce the result you want if the result is
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1299 one of the hours straddling the moment the standard offset changes.
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1300
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1301 Skipping code for error cases, the default \method{fromutc()}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1302 implementation acts like:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1303
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1304 \begin{verbatim}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1305 def fromutc(self, dt):
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1306 # raise ValueError error if dt.tzinfo is not self
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1307 dtoff = dt.utcoffset()
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1308 dtdst = dt.dst()
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1309 # raise ValueError if dtoff is None or dtdst is None
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1310 delta = dtoff - dtdst # this is self's standard offset
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1311 if delta:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1312 dt += delta # convert to standard local time
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1313 dtdst = dt.dst()
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1314 # raise ValueError if dtdst is None
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1315 if dtdst:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1316 return dt + dtdst
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1317 else:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1318 return dt
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1319 \end{verbatim}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1320 \end{methoddesc}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1321
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1322 Example \class{tzinfo} classes:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1323
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1324 \verbatiminput{tzinfo-examples.py}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1325
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1326 Note that there are unavoidable subtleties twice per year in a
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1327 \class{tzinfo}
27082 64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1328 subclass accounting for both standard and daylight time, at the DST
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1329 transition points. For concreteness, consider US Eastern (UTC -0500),
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1330 where EDT begins the minute after 1:59 (EST) on the first Sunday in
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1331 April, and ends the minute after 1:59 (EDT) on the last Sunday in October:
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1332
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1333 \begin{verbatim}
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1334 UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1335 EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1336 EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1337
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1338 start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1339
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1340 end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1341 \end{verbatim}
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1342
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1343 When DST starts (the "start" line), the local wall clock leaps from 1:59
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1344 to 3:00. A wall time of the form 2:MM doesn't really make sense on that
27089 a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1345 day, so \code{astimezone(Eastern)} won't deliver a result with
31283 d6d1efdcc5fd lots of markup adjustments Fred Drake <fdrake@acm.org> parents: 30349 diff changeset	1346 \code{hour == 2} on the
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1347 day DST begins. In order for \method{astimezone()} to make this
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1348 guarantee, the \method{rzinfo.dst()} method must consider times
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1349 in the "missing hour" (2:MM for Eastern) to be in daylight time.
27082 64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1350
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1351 When DST ends (the "end" line), there's a potentially worse problem:
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1352 there's an hour that can't be spelled unambiguously in local wall time:
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1353 the last hour of daylight time. In Eastern, that's times of
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1354 the form 5:MM UTC on the day daylight time ends. The local wall clock
27082 64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1355 leaps from 1:59 (daylight time) back to 1:00 (standard time) again.
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1356 Local times of the form 1:MM are ambiguous. \method{astimezone()} mimics
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1357 the local clock's behavior by mapping two adjacent UTC hours into the
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1358 same local hour then. In the Eastern example, UTC times of the form
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1359 5:MM and 6:MM both map to 1:MM when converted to Eastern. In order for
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1360 \method{astimezone()} to make this guarantee, the \method{tzinfo.dst()}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1361 method must consider times in the "repeated hour" to be in
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1362 standard time. This is easily arranged, as in the example, by expressing
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1363 DST switch times in the time zone's standard local time.
27082 64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1364
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1365 Applications that can't bear such ambiguities should avoid using hybrid
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1366 \class{tzinfo} subclasses; there are no ambiguities when using UTC, or
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1367 any other fixed-offset \class{tzinfo} subclass (such as a class
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1368 representing only EST (fixed offset -5 hours), or only EDT (fixed offset
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1369 -4 hours)).
27082 64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1370
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1371
37283 5203376f1589 Bug #1459103: add inter-section links for strftime section. Georg Brandl <georg@python.org> parents: 35996 diff changeset	1372 \subsection{\method{strftime()} Behavior\label{strftime-behavior}}
26765 095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1373
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1374 \class{date}, \class{datetime}, and \class{time}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1375 objects all support a \code{strftime(\var{format})}
26765 095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1376 method, to create a string representing the time under the control of
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1377 an explicit format string. Broadly speaking,
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1378 \code{d.strftime(fmt)}
26765 095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1379 acts like the \refmodule{time} module's
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1380 \code{time.strftime(fmt, d.timetuple())}
26765 095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1381 although not all objects support a \method{timetuple()} method.
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1382
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1383 For \class{time} objects, the format codes for
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1384 year, month, and day should not be used, as time objects have no such
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1385 values. If they're used anyway, \code{1900} is substituted for the
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1386 year, and \code{0} for the month and day.
26765 095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1387
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1388 For \class{date} objects, the format codes for hours, minutes, and
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1389 seconds should not be used, as \class{date} objects have no such
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1390 values. If they're used anyway, \code{0} is substituted for them.
26765 095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1391
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	1392 For a naive object, the \code{\%z} and \code{\%Z} format codes are
26765 095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1393 replaced by empty strings.
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1394
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1395 For an aware object:
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1396
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1397 \begin{itemize}
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1398 \item[\code{\%z}]
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1399 \method{utcoffset()} is transformed into a 5-character string of
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1400 the form +HHMM or -HHMM, where HH is a 2-digit string giving the
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1401 number of UTC offset hours, and MM is a 2-digit string giving the
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1402 number of UTC offset minutes. For example, if
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1403 \method{utcoffset()} returns \code{timedelta(hours=-3, minutes=-30)},
26785 0b34f51eab4e tzinfo.{utcoffset,dst} can return timedelta (or integer or None). Tim Peters <tim.peters@gmail.com> parents: 26773 diff changeset	1404 \code{\%z} is replaced with the string \code{'-0330'}.
26765 095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1405
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1406 \item[\code{\%Z}]
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1407 If \method{tzname()} returns \code{None}, \code{\%Z} is replaced
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1408 by an empty string. Otherwise \code{\%Z} is replaced by the returned
26765 095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1409 value, which must be a string.
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1410 \end{itemize}
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1411
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1412 The full set of format codes supported varies across platforms,
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1413 because Python calls the platform C library's \function{strftime()}
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1414 function, and platform variations are common. The documentation for
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1415 Python's \refmodule{time} module lists the format codes that the C
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1416 standard (1989 version) requires, and those work on all platforms
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1417 with a standard C implementation. Note that the 1999 version of the
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1418 C standard added additional format codes.
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1419
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1420 The exact range of years for which \method{strftime()} works also
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1421 varies across platforms. Regardless of platform, years before 1900
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1422 cannot be used.
35996 dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1423
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1424 \subsection{Examples}
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1425
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1426 \subsubsection{Creating Datetime Objects from Formatted Strings}
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1427
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1428 The \class{datetime} class does not directly support parsing formatted time
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1429 strings. You can use \function{time.strptime} to do the parsing and create
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1430 a \class{datetime} object from the tuple it returns:
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1431
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1432 \begin{verbatim}
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1433 >>> s = "2005-12-06T12:13:14"
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1434 >>> from datetime import datetime
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1435 >>> from time import strptime
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1436 >>> datetime(*strptime(s, "%Y-%m-%dT%H:%M:%S")[0:6])
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1437 datetime.datetime(2005, 12, 6, 12, 13, 14)
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1438 \end{verbatim}
dbcc8912a24d add common usage example Skip Montanaro <skip@pobox.com> parents: 34448 diff changeset	1439

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libdatetime.tex @ 39042:c02fa187e0f4 legacy-trunk