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

annotate Doc/lib/libdatetime.tex @ 27089:a123793ca193 legacy-trunk

datetime_from_timet_and_us(): ignore leap seconds if the platform localtime()/gmtime() insists on delivering them, + associated doc changes. Redid the docs for datetimtez.astimezone().

author	Tim Peters <tim.peters@gmail.com>
date	Sat, 04 Jan 2003 18:17:36 +0000
parents	64e8c6986610
children	faba6e6c824d

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 \sectionauthor{Raymond D. Hettinger}{python@rcn.com}
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	12
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	13 \versionadded{2.3}
26704 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
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	16 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	17 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	18 arithmetic is supported, the focus of the implementation is on
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	19 efficient field extraction, for output formatting and manipulation.
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	20
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	21 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	22 This distinction refers to whether the object has any notion of time
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	23 zone, daylight savings time, or other kind of algorithmic or political
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	24 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	25 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	26 timezone is purely up to the program, just like it's up to the program
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	27 whether a particular number represents meters, miles, or mass. Naive
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	28 \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	29 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	30
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	31 For applications requiring more, ``aware'' \class{datetime} subclasses add an
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	32 optional time zone information object to the basic naive classes.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	33 These \class{tzinfo} objects capture information about the offset from
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	34 UTC time, the time zone name, and whether Daylight Savings Time is in
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	35 effect. Note that no concrete \class{tzinfo} classes are supplied by
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	36 the \module{datetime} module. Instead, they provide a framework for
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	37 incorporating the level of detail an app may require. The rules for
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	38 time adjustment across the world are more political than rational, and
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	39 there is no standard suitable for every app.
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	40
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	41 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	42
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	43 \begin{datadesc}{MINYEAR}
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	44 The smallest year number allowed in a \class{date},
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	45 \class{datetime}, or \class{datetimetz} object. \constant{MINYEAR}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	46 is \code{1}.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	47 \end{datadesc}
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	48
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	49 \begin{datadesc}{MAXYEAR}
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	50 The largest year number allowed in a \class{date}, \class{datetime},
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	51 or \class{datetimetz} 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	52 \end{datadesc}
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	53
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	54 \begin{seealso}
26965 b790da0671f7 Spelling fix Raymond Hettinger <python@rcn.com> parents: 26962 diff changeset	55 \seemodule{calendar}{General calendar related functions.}
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	56 \seemodule{time}{Time access and conversions.}
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	57 \end{seealso}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	58
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	59 \subsection{Available Types}
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	60
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	61 \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	62 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	63 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	64 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	65 \end{classdesc*}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	66
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	67 \begin{classdesc*}{time}
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	68 An idealized naive 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	69 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	70 of "leap seconds" here).
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	71 Attributes: \member{hour}, \member{minute}, \member{second}, and
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	72 \member{microsecond}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	73 \end{classdesc*}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	74
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	75 \begin{classdesc*}{datetime}
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	76 A combination of a naive date and a naive time.
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	77 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	78 \member{hour}, \member{minute}, \member{second},
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	79 and \member{microsecond}.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	80 \end{classdesc*}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	81
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	82 \begin{classdesc*}{timedelta}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	83 A duration, expressing the difference between two \class{date},
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	84 \class{time}, or \class{datetime} instances, to microsecond
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	85 resolution.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	86 \end{classdesc*}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	87
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	88 \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	89 An abstract base class for time zone information objects. These
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	90 are used by the \class{datetimetz} and \class{timetz} classes to
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	91 provided a customizable notion of time adjustment (for example, to
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	92 account for time zone and/or daylight savings time).
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	93 \end{classdesc*}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	94
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	95 \begin{classdesc*}{timetz}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	96 An aware subclass of \class{time}, supporting a customizable notion of
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	97 time adjustment.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	98 \end{classdesc*}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	99
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	100 \begin{classdesc*}{datetimetz}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	101 An aware subclass of \class{datetime}, supporting a customizable notion of
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	102 time adjustment.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	103 \end{classdesc*}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	104
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	105 Objects of these types are immutable.
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	106
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	107 Objects of the \class{date}, \class{datetime}, and \class{time} types
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	108 are always naive.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	109
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	110 An object \var{d} of type \class{timetz} or \class{datetimetz} may be
6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	111 naive or aware. \var{d} is aware if \code{\var{d}.tzinfo} is not
6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	112 \code{None}, and \code{\var{d}.tzinfo.utcoffset(\var{d})} does not return
6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	113 \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	114 \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	115 \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	116 is naive.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	117
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	118 The distinction between naive and aware doesn't apply to
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	119 \code{timedelta} objects.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	120
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	121 Subclass relationships:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	122
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	123 \begin{verbatim}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	124 object
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	125 timedelta
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	126 tzinfo
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	127 time
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	128 timetz
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	129 date
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	130 datetime
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	131 datetimetz
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	132 \end{verbatim}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	133
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	134 \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	135
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	136 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	137 between two dates or times.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	138
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	139 \begin{classdesc}{timedelta}{days=0, seconds=0, microseconds=0,
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	140 milliseconds=0, minutes=0, hours=0, weeks=0}
26970 4448ff8b3239 Use funcdesc instead of classdesc to be consistent with out sections. Raymond Hettinger <python@rcn.com> parents: 26965 diff changeset	141
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	142 All arguments are optional. Arguments may be ints, longs, or floats,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	143 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	144
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	145 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	146 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	147
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	148 \begin{verbatim}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	149 A millisecond is converted to 1000 microseconds.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	150 A minute is converted to 60 seconds.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	151 An hour is converted to 3600 seconds.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	152 A week is converted to 7 days.
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	153 \end{verbatim}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	154
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	155 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	156 representation is unique, with
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	157
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	158 \begin{itemize}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	159 \item \code{0 <= \var{microseconds} < 1000000}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	160 \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	161 \item \code{-999999999 <= \var{days} <= 999999999}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	162 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	163
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	164 If any argument is a float, and there are fractional microseconds,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	165 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	166 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	167 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	168 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	169
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	170 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	171 \exception{OverflowError} is raised.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	172
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	173 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	174 For example,
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	175
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	176 \begin{verbatim}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	177 >>> 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	178 >>> (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	179 (-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	180 \end{verbatim}
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	181 \end{classdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	182
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	183 Class attributes are:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	184
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	185 \begin{memberdesc}{min}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	186 The most negative \class{timedelta} object,
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	187 \code{timedelta(-999999999)}.
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	188 \end{memberdesc}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	189
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	190 \begin{memberdesc}{max}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	191 The most positive \class{timedelta} object,
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	192 \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	193 microseconds=999999)}.
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	194 \end{memberdesc}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	195
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	196 \begin{memberdesc}{resolution}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	197 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	198 \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	199 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	200
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	201 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	202 \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	203 a \class{timedelta} object.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	204
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	205 Instance attributes (read-only):
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	206
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	207 \begin{tableii}{c\|l}{code}{Attribute}{Value}
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	208 \lineii{days}{Between -999999999 and 999999999 inclusive}
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	209 \lineii{seconds}{Between 0 and 86399 inclusive}
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	210 \lineii{microseconds}{Between 0 and 999999 inclusive}
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	211 \end{tableii}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	212
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	213 Supported operations:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	214
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	215 \begin{tableiii}{c\|l\|c}{code}{Operation}{Result}{Notes}
26872 f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	216 \lineiii{\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	217 {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	218 Afterwards \var{t1}-\var{t2} == \var{t3} and \var{t1}-\var{t3}
f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	219 == \var{t2} are true.}
f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	220 {(1)}
f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	221 \lineiii{\var{t1} = \var{t2} - \var{t3}}
f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	222 {Difference of \var{t2} and \var{t3}. Afterwards \var{t1} ==
f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	223 \var{t2} - \var{t3} and \var{t2} == \var{t1} + \var{t3} are
f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	224 true.}
f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	225 {(1)}
f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	226 \lineiii{\var{t1} = \var{t2} * \var{i} or \var{t1} = \var{i} * \var{t2}}
f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	227 {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	228 Afterwards \var{t1} // i == \var{t2} is true,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	229 provided \code{i != 0}.
26872 f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	230 In general, \var{t1} * i == \var{t1} * (i-1) + \var{t1} is true.}
f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	231 {(1)}
f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	232 \lineiii{\var{t1} = \var{t2} // \var{i}}
f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	233 {The floor is computed and the remainder (if any) is thrown away.}
27037 99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	234 {(3)}
26951 94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	235 \lineiii{+\var{t1}}
26962 b9c462d23f3c Add markup for time object. Raymond Hettinger <python@rcn.com> parents: 26958 diff changeset	236 {Returns a \class{timedelta} object with the same value.}
27037 99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	237 {(2)}
26951 94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	238 \lineiii{-\var{t1}}
26962 b9c462d23f3c Add markup for time object. Raymond Hettinger <python@rcn.com> parents: 26958 diff changeset	239 {equivalent to \class{timedelta}(-\var{t1.days}, -\var{t1.seconds},
b9c462d23f3c Add markup for time object. Raymond Hettinger <python@rcn.com> parents: 26958 diff changeset	240 -\var{t1.microseconds}),and to \var{t1}* -1.}
27037 99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	241 {(1)(4)}
26951 94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	242 \lineiii{abs(\var{t})}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	243 {equivalent to +\var{t} when \code{t.days >= 0}, and to
27037 99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	244 -\var{t} when \code{t.days < 0}.
99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	245 overflow.}
99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	246 {(2)}
26872 f483efca224c Clean up a table so it passes formatting. Fred Drake <fdrake@acm.org> parents: 26870 diff changeset	247 \end{tableiii}
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	248 \noindent
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	249 Notes:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	250
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	251 \begin{description}
83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	252 \item[(1)]
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	253 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	254
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	255 \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	256 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	257
99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	258 \item[(3)]
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	259 Division by 0 raises \exception{ZeroDivisionError}.
26951 94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	260
27037 99df0e52f634 The tzinfo methods utcoffset() and dst() must return a timedelta object Tim Peters <tim.peters@gmail.com> parents: 27034 diff changeset	261 \item[(4)]
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	262 -\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	263 \end{description}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	264
26951 94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	265 In addition to the operations listed above \class{timedelta} objects
94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	266 support certain additions and subtractions with \class{date},
94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	267 \class{datetime}, and \class{datimetz} objects (see below).
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	268
26951 94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	269 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	270 \class{timedelta} object representing the smaller duration considered
94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	271 to be the smaller timedelta.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	272
26951 94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	273 \class{timedelta} objects are hashable (usable as dictionary key),
94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	274 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	275 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	276 \code{timedelta(0)}.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	277
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	278
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	279 \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	280
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	281 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	282 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	283 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	284 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	285 "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	286 \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	287 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	288 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	289
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	290 \begin{classdesc}{date}{year, month, day}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	291 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	292 following ranges:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	293
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	294 \begin{itemize}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	295 \item \code{MINYEAR <= \var{year} <= MAXYEAR}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	296 \item \code{1 <= \var{month} <= 12}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	297 \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	298 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	299
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	300 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	301 is raised.
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	302 \end{classdesc}
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 Other constructors, all class methods:
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	305
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	306 \begin{methoddesc}{today}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	307 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	308 \code{date.fromtimestamp(time.time())}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	309 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	310
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	311 \begin{methoddesc}{fromtimestamp}{timestamp}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	312 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	313 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	314 \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	315 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	316 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	317 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	318 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	319 \method{fromtimestamp()}.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	320
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	321 \begin{methoddesc}{fromordinal}{ordinal}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	322 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	323 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	324 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	325 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	326 \var{d}}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	327 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	328
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	329 Class attributes:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	330
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	331 \begin{memberdesc}{min}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	332 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	333 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	334
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	335 \begin{memberdesc}{max}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	336 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	337 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	338
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	339 \begin{memberdesc}{resolution}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	340 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	341 objects, \code{timedelta(days=1)}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	342 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	343
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	344 Instance attributes (read-only):
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	345
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	346 \begin{memberdesc}{year}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	347 Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	348 \end{memberdesc}
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	349
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	350 \begin{memberdesc}{month}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	351 Between 1 and 12 inclusive.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	352 \end{memberdesc}
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	353
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	354 \begin{memberdesc}{day}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	355 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	356 year.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	357 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	358
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	359 Supported operations:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	360
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	361 \begin{itemize}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	362 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	363 date1 + timedelta -> date2
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	364 timedelta + date1 -> date2
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	365 date2 is timedelta.days days removed from the date1, moving forward
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	366 in time if timedelta.days > 0, or backward if timedetla.days < 0.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	367 date2 - date1 == timedelta.days after. timedelta.seconds and
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	368 timedelta.microseconds are ignored. \exception{OverflowError} is
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	369 raised if date2.year would be smaller than \constant{MINYEAR} or
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	370 larger than \constant{MAXYEAR}.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	371
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	372 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	373 date1 - timedelta -> date2
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	374 Computes the date2 such that date2 + timedelta == date1. This
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	375 isn't quite equivalent to date1 + (-timedelta), because -timedelta
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	376 in isolation can overflow in cases where date1 - timedelta does
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	377 not. timedelta.seconds and timedelta.microseconds are ignored.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	378
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	379 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	380 date1 - date2 -> timedelta
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	381 This is exact, and cannot overflow. timedelta.seconds and
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	382 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	383 after.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	384
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	385 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	386 comparison of date to date, where date1 is considered less than
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	387 date2 when date1 precedes date2 in time. In other words,
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	388 date1 < date2 if and only if date1.toordinal() < date2.toordinal().
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	389
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	390 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	391 hash, use as dict key
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	392
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	393 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	394 efficient pickling
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	395
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	396 \item
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	397 in Boolean contexts, all \class{date} objects are considered to be true
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	398 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	399
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	400 Instance methods:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	401
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	402 \begin{methoddesc}{replace}{year, month, day}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	403 Return a date with the same value, except for those fields given
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	404 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	405 example, if \code{d == date(2002, 12, 31)}, then
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	406 \code{d.replace(day=26) == date(2000, 12, 26)}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	407 \end{methoddesc}
26773 0f1405ace437 Implemented .replace() methods for date, datetime, datetimetz, time and Tim Peters <tim.peters@gmail.com> parents: 26765 diff changeset	408
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	409 \begin{methoddesc}{timetuple}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	410 Return a 9-element tuple of the form returned by
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	411 \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	412 0, and the DST flag is -1.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	413 \code{\var{d}.timetuple()} is equivalent to
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	414 \code{(\var{d}.year, \var{d}.month, \var{d}.day,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	415 0, 0, 0, \# h, m, s
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	416 \var{d}.weekday(), \# 0 is Monday
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	417 \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	418 \# day of year
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	419 -1)}
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	420 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	421
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	422 \begin{methoddesc}{toordinal}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	423 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	424 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	425 \code{date.fromordinal(\var{d}.toordinal()) == \var{d}}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	426 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	427
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	428 \begin{methoddesc}{weekday}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	429 Return the day of the week as an integer, where Monday is 0 and
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	430 Sunday is 6. For example, date(2002, 12, 4).weekday() == 2, a
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	431 Wednesday.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	432 See also \method{isoweekday()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	433 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	434
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	435 \begin{methoddesc}{isoweekday}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	436 Return the day of the week as an integer, where Monday is 1 and
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	437 Sunday is 7. For example, date(2002, 12, 4).isoweekday() == 3, a
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	438 Wednesday.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	439 See also \method{weekday()}, \method{isocalendar()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	440 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	441
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	442 \begin{methoddesc}{isocalendar}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	443 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	444
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	445 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	446 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	447 for a good explanation.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	448
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	449 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	450 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	451 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	452 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	453 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	454
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	455 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	456 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	457 2004, so that
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	458
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	459 date(2003, 12, 29).isocalendar() == (2004, 1, 1)
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	460 date(2004, 1, 4).isocalendar() == (2004, 1, 7)
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	461 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	462
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	463 \begin{methoddesc}{isoformat}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	464 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	465 'YYYY-MM-DD'. For example,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	466 date(2002, 12, 4).isoformat() == '2002-12-04'.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	467 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	468
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	469 \begin{methoddesc}{__str__}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	470 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	471 \code{\var{d}.isoformat()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	472 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	473
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	474 \begin{methoddesc}{ctime}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	475 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	476 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	477 \code{\var{d}.ctime()} is equivalent to
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	478 \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	479 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	480 (which \function{time.ctime()} invokes, but which
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	481 \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	482 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	483
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	484 \begin{methoddesc}{strftime}{format}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	485 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	486 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	487 will see 0 values.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	488 See the section on \method{strftime()} behavior.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	489 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	490
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	491
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	492 \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	493
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	494 A \class{datetime} object is a single object containing all the
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	495 information from a \class{date} object and a time object. Like a
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	496 \class{date} object, \class{datetime} assumes the current Gregorian
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	497 calendar extended in both directions; like a time object,
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	498 \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	499 day.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	500
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	501 \begin{classdesc}{datetime}{year, month, day,
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	502 hour=0, minute=0, second=0, microsecond=0}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	503 The year, month and day arguments are required. Arguments may be
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	504 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	505
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	506 \begin{itemize}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	507 \item \code{\member{MINYEAR} <= \var{year} <= \member{MAXYEAR}}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	508 \item \code{1 <= \var{month} <= 12}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	509 \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	510 \item \code{0 <= \var{hour} < 24}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	511 \item \code{0 <= \var{minute} < 60}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	512 \item \code{0 <= \var{second} < 60}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	513 \item \code{0 <= \var{microsecond} < 1000000}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	514 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	515
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	516 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	517 is raised.
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	518 \end{classdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	519
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	520 Other constructors, all class methods:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	521
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	522 \begin{methoddesc}{today}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	523 Return the current local datetime. This is equivalent to
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	524 \code{datetime.fromtimestamp(time.time())}.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	525 See also \method{now()}, \method{fromtimestamp()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	526 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	527
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	528 \begin{methoddesc}{now}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	529 Return the current local datetime. This is like \method{today()},
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	530 but, if possible, supplies more precision than can be gotten from
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	531 going through a \function{time.time()} timestamp (for example,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	532 this may be possible on platforms that supply the C
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	533 \cfunction{gettimeofday()} function).
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	534 See also \method{today()}, \method{utcnow()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	535 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	536
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	537 \begin{methoddesc}{utcnow}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	538 Return the current UTC datetime. This is like \method{now()}, but
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	539 returns the current UTC date and time.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	540 See also \method{now()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	541 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	542
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	543 \begin{methoddesc}{fromtimestamp}{timestamp}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	544 Return the local \class{datetime} corresponding to the \POSIX{}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	545 timestamp, such as is returned by \function{time.time()}. This
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	546 may raise \exception{ValueError}, if the timestamp is out of the
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	547 range of values supported by the platform C
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	548 \cfunction{localtime()} 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	549 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	550 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	551 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	552 \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	553 differing by a second that yield identical \class{datetime} objects.
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	554 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	555 See also \method{utcfromtimestamp()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	556 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	557
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	558 \begin{methoddesc}{utcfromtimestamp}{timestamp}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	559 Return the UTC \class{datetime} corresponding to the \POSIX{}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	560 timestamp. This may raise \exception{ValueError}, if the
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	561 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	562 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	563 restricted to years in 1970 through 2038.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	564 See also \method{fromtimestamp()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	565 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	566
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	567 \begin{methoddesc}{fromordinal}{ordinal}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	568 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	569 Gregorian ordinal, where January 1 of year 1 has ordinal 1.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	570 \exception{ValueError} is raised unless 1 <= ordinal <=
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	571 datetime.max.toordinal(). The hour, minute, second and
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	572 microsecond of the result are all 0.
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
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	575 \begin{methoddesc}{combine}{date, time}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	576 Return a new \class{datetime} object whose date components are
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	577 equal to the given \class{date} object's, and whose time
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	578 components are equal to the given time object's. For any
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	579 \class{datetime} object \var{d}, \code{\var{d} ==
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	580 datetime.combine(\var{d}.date(), \var{d}.time())}. If date is a
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	581 \class{datetime} or \class{datetimetz} object, its time components
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	582 are ignored. If date is \class{datetimetz} object, its
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	583 \member{tzinfo} component is also ignored. If time is a
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	584 \class{timetz} object, its \member{tzinfo} component is ignored.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	585 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	586
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	587 Class attributes:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	588
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	589 \begin{memberdesc}{min}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	590 The earliest representable \class{datetime},
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	591 \code{datetime(MINYEAR, 1, 1)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	592 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	593
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	594 \begin{memberdesc}{max}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	595 The latest representable \class{datetime},
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	596 \code{datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	597 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	598
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	599 \begin{memberdesc}{resolution}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	600 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	601 objects, \code{timedelta(microseconds=1)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	602 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	603
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	604 Instance attributes (read-only):
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	605
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	606 \begin{memberdesc}{year}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	607 Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	608 \end{memberdesc}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	609
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	610 \begin{memberdesc}{month}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	611 Between 1 and 12 inclusive
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	612 \end{memberdesc}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	613
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	614 \begin{memberdesc}{day}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	615 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	616 year.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	617 \end{memberdesc}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	618
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	619 \begin{memberdesc}{hour}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	620 In \code{range(24)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	621 \end{memberdesc}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	622
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	623 \begin{memberdesc}{minute}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	624 In \code{range(60)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	625 \end{memberdesc}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	626
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	627 \begin{memberdesc}{second}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	628 In \code{range(60)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	629 \end{memberdesc}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	630
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	631 \begin{memberdesc}{microsecond}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	632 In \code{range(1000000)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	633 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	634
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	635 Supported operations:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	636
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	637 \begin{itemize}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	638 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	639 datetime1 + timedelta -> datetime2
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	640 timedelta + datetime1 -> datetime2
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	641 datetime2 is a duration of timedelta removed from datetime1, moving
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	642 forward in time if timedelta.days > 0, or backward if
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	643 timedelta.days < 0. datetime2 - datetime1 == timedelta after.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	644 \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	645 smaller than \constant{MINYEAR} or larger than \constant{MAXYEAR}.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	646
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	647 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	648 datetime1 - timedelta -> datetime2
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	649 Computes the datetime2 such that datetime2 + timedelta == datetime1.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	650 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	651 -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	652 datetime1 - timedelta does not.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	653
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	654 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	655 datetime1 - datetime2 -> timedelta
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	656 This is exact, and cannot overflow.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	657 datetime2 + timedelta == datetime1 after.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	658
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	659 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	660 comparison of \class{datetime} to datetime, where datetime1 is
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	661 considered less than datetime2 when datetime1 precedes datetime2
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	662 in time.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	663
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	664 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	665 hash, use as dict key
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	666
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	667 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	668 efficient pickling
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	669
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	670 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	671 in Boolean contexts, all \class{datetime} objects are considered
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	672 to be true
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	673 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	674
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	675 Instance methods:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	676
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	677 \begin{methoddesc}{date}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	678 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	679 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	680
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	681 \begin{methoddesc}{time}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	682 Return time object with same hour, minute, second and microsecond.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	683 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	684
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	685 \begin{methoddesc}{replace}{year=, month=, day=, hour=, minute=,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	686 second=, microsecond=}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	687 Return a datetime with the same value, except for those fields given
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	688 new values by whichever keyword arguments are specified.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	689 \end{methoddesc}
26773 0f1405ace437 Implemented .replace() methods for date, datetime, datetimetz, time and Tim Peters <tim.peters@gmail.com> parents: 26765 diff changeset	690
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	691 \begin{methoddesc}{astimezone}{tz}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	692 Return a \class{datetimetz} with the same date and time fields, and
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	693 with \member{tzinfo} member \var{tz}. \var{tz} must be \code{None},
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	694 or an instance of a \class{tzinfo} subclass.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	695 \end{methoddesc}
26792 816b8ddccfe1 Implemented datetime.astimezone() and datetimetz.astimezone(). Tim Peters <tim.peters@gmail.com> parents: 26787 diff changeset	696
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	697 \begin{methoddesc}{timetuple}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	698 Return a 9-element tuple of the form returned by
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	699 \function{time.localtime()}.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	700 The DST flag is -1. \code{\var{d}.timetuple()} is equivalent to
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	701 \code{(\var{d}.year, \var{d}.month, \var{d}.day,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	702 \var{d}.hour, \var{d}.minute, \var{d}.second,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	703 \var{d}.weekday(), \# 0 is Monday
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	704 \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	705 \# day of year
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	706 -1)}
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	707 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	708
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	709 \begin{methoddesc}{toordinal}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	710 Return the proleptic Gregorian ordinal of the date. The same as
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	711 \method{date.toordinal()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	712 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	713
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	714 \begin{methoddesc}{weekday}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	715 Return the day of the week as an integer, where Monday is 0 and
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	716 Sunday is 6. The same as \method{date.weekday()}.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	717 See also \method{isoweekday()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	718 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	719
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	720 \begin{methoddesc}{isoweekday}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	721 Return the day of the week as an integer, where Monday is 1 and
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	722 Sunday is 7. The same as \method{date.isoweekday()}.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	723 See also \method{weekday()}, \method{isocalendar()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	724 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	725
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	726 \begin{methoddesc}{isocalendar}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	727 Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	728 same as \method{date.isocalendar()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	729 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	730
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	731 \begin{methoddesc}{isoformat}{sep='T'}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	732 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	733 YYYY-MM-DDTHH:MM:SS.mmmmmm
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	734 or, if self.microsecond is 0,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	735 YYYY-MM-DDTHH:MM:SS
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	736 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	737 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	738 of the result. For example,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	739 datetime(2002, 12, 4, 1, 2, 3, 4).isoformat(' ') ==
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	740 '2002-12-04 01:02:03.000004'
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	741 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	742
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	743 \begin{methoddesc}{__str__}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	744 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	745 equivalent to \code{\var{d}.isoformat(' ')}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	746 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	747
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	748 \begin{methoddesc}{ctime}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	749 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	750 datetime(2002, 12, 4, 20, 30, 40).ctime() == 'Wed Dec 4 20:30:40 2002'.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	751 \code{d.ctime()} is equivalent to
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	752 \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	753 the native C \cfunction{ctime()} function (which
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	754 \function{time.ctime()} invokes, but which
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	755 \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	756 standard.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	757 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	758
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	759 \begin{methoddesc}{strftime}{format}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	760 Return a string representing the date and time, controlled by an
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	761 explicit format string. See the section on \method{strftime()}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	762 behavior.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	763 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	764
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	765
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	766 \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	767
26962 b9c462d23f3c Add markup for time object. Raymond Hettinger <python@rcn.com> parents: 26958 diff changeset	768 A \class{time} object represents an idealized time of day, independent
b9c462d23f3c Add markup for time object. Raymond Hettinger <python@rcn.com> parents: 26958 diff changeset	769 of day and timezone.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	770
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	771 \begin{classdesc}{time}{hour=0, minute=0, second=0, microsecond=0}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	772 All arguments are optional. They may be ints or longs, in the
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	773 following ranges:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	774
26962 b9c462d23f3c Add markup for time object. Raymond Hettinger <python@rcn.com> parents: 26958 diff changeset	775 \begin{itemize}
b9c462d23f3c Add markup for time object. Raymond Hettinger <python@rcn.com> parents: 26958 diff changeset	776 \item \code{0 <= \var{hour} < 24}
b9c462d23f3c Add markup for time object. Raymond Hettinger <python@rcn.com> parents: 26958 diff changeset	777 \item \code{0 <= \var{minute} < 60}
b9c462d23f3c Add markup for time object. Raymond Hettinger <python@rcn.com> parents: 26958 diff changeset	778 \item \code{0 <= \var{second} < 60}
b9c462d23f3c Add markup for time object. Raymond Hettinger <python@rcn.com> parents: 26958 diff changeset	779 \item \code{0 <= \var{microsecond} < 1000000}
b9c462d23f3c Add markup for time object. Raymond Hettinger <python@rcn.com> parents: 26958 diff changeset	780 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	781
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	782 If an argument outside those ranges is given, \exception{ValueError}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	783 is raised.
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	784 \end{classdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	785
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	786 Class attributes:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	787
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	788 \begin{memberdesc}{min}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	789 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	790 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	791
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	792 \begin{memberdesc}{max}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	793 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	794 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	795
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	796 \begin{memberdesc}{resolution}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	797 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	798 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	799 arithmetic on \class{time} objects is not supported.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	800 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	801
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	802 Instance attributes (read-only):
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	803
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	804 \begin{memberdesc}{hour}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	805 In \code{range(24)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	806 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	807
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	808 \begin{memberdesc}{minute}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	809 In \code{range(60)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	810 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	811
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	812 \begin{memberdesc}{second}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	813 In \code{range(60)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	814 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	815
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	816 \begin{memberdesc}{microsecond}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	817 In \code{range(1000000)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	818 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	819
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	820 Supported operations:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	821
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	822 \begin{itemize}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	823 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	824 comparison of time to time, where time1 is considered
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	825 less than time2 when time1 precedes time2 in time.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	826
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	827 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	828 hash, use as dict key
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	829
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	830 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	831 efficient pickling
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	832
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	833 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	834 in Boolean contexts, a time object is considered to be true
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	835 if and only if it isn't equal to \code{time(0)}
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	836 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	837
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	838 Instance methods:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	839
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	840 \begin{methoddesc}{replace}{hour=, minute=, second=, microsecond=}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	841 Return a time with the same value, except for those fields given
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	842 new values by whichever keyword arguments are specified.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	843 \end{methoddesc}
26773 0f1405ace437 Implemented .replace() methods for date, datetime, datetimetz, time and Tim Peters <tim.peters@gmail.com> parents: 26765 diff changeset	844
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	845 \begin{methoddesc}{isoformat}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	846 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	847 HH:MM:SS.mmmmmm
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	848 or, if self.microsecond is 0
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	849 HH:MM:SS
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	850 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	851
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	852 \begin{methoddesc}{__str__}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	853 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	854 \code{\var{t}.isoformat()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	855 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	856
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	857 \begin{methoddesc}{strftime}{format}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	858 Return a string representing the time, controlled by an explicit
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	859 format string. See the section on \method{strftime()} behavior.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	860 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	861
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	862
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	863 \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	864
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	865 \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	866 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	867 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	868 \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	869 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	870 subclasses of \class{tzinfo}.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	871
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	872 An instance of (a concrete subclass of) \class{tzinfo} can be passed
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	873 to the constructors for \class{datetimetz} and \class{timetz} objects.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	874 The latter objects view their fields as being in local time, and the
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	875 \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	876 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	877 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	878
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	879 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	880 \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	881 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	882 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	883
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	884 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	885 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	886 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	887 implement all of them.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	888
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	889 \begin{methoddesc}{utcoffset}{self, dt}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	890 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	891 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	892 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	893 \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	894 \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	895 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	896 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	897 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	898 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	899 \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	900
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	901 \begin{verbatim}
27008 4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	902 return CONSTANT # fixed-offset class
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	903 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	904 \end{verbatim}
27034 dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	905
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	906 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	907 \method{dst()} should not return \code{None} either.
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
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	910
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	911 \begin{methoddesc}{dst}{self, dt}
27008 4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	912 Return the daylight savings time (DST) adjustment, in minutes east of
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	913 UTC, or \code{None} if DST information isn't known. Return \code{0} if
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	914 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	915 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	916 \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	917 Note that DST offset, if applicable, has
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	918 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	919 \method{utcoffset()}, so there's no need to consult \method{dst()}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	920 unless you're interested in displaying DST info separately. For
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	921 example, \method{datetimetz.timetuple()} calls its \member{tzinfo}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	922 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	923 \member{tm_isdst} flag should be set, and
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	924 \method{datetimetz.astimezone()} calls \method{dst()} to account for
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	925 DST changes when crossing time zones.
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	926
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	927 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	928 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	929
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	930 \code{tz.utcoffset(dt) - tz.dst(dt)}
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	931
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	932 must return the same result for every \class{datetimetz} \var{dt}
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	933 with \code{dt.tzinfo==tz} For sane \class{tzinfo} subclasses, this
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	934 expression yields the time zone's "standard offset", which should not
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	935 depend on the date or the time, but only on geographic location. The
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	936 implementation of \method{datetimetz.astimezone()} relies on this, but
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	937 cannot detect violations; it's the programmer's responsibility to
27008 4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	938 ensure it.
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	939
27034 dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	940 \begin{methoddesc}{tzname}{self, dt}
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	941 Return the timezone name corresponding to the \class{datetime} represented
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	942 by \var{dt}, as a string. Nothing about string names is defined by the
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	943 \module{datetime} module, and there's no requirement that it mean anything
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	944 in particular. For example, "GMT", "UTC", "-500", "-5:00", "EDT",
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	945 "US/Eastern", "America/New York" are all valid replies. Return
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	946 \code{None} if a string name isn't known. Note that this is a method
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	947 rather than a fixed string primarily because some \class{tzinfo} objects
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	948 will wish to return different names depending on the specific value
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	949 of \var{dt} passed, especially if the \class{tzinfo} class is
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	950 accounting for daylight time.
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	951 \end{methoddesc}
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	952
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	953 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	954
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	955 These methods are called by a \class{datetimetz} or \class{timetz} object,
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	956 in response to their methods of the same names. A \class{datetimetz}
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	957 object passes itself as the argument, and a \class{timetz} object passes
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	958 \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	959 therefore be prepared to accept a \var{dt} argument of \code{None}, or of
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	960 class \class{datetimetz}.
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	961
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	962 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	963 best response. For example, returning \code{None} is appropriate if 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	964 class wishes to say that timetz objects don't participate in 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	965 \class{tzinfo} protocol. In other applications, it may be more useful
26951 94bc812a3c52 Complete the markup for timedelta objects. Raymond Hettinger <python@rcn.com> parents: 26924 diff changeset	966 for \code{utcoffset(None)} to return the standard UTC 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	967
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	968 When a \class{datetimetz} object is passed in response to a
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	969 \class{datetimetz} method, \code{dt.tzinfo} is the same object as
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	970 \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	971 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	972 the \class{tzinfo} methods interpret \var{dt} as being in local time,
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	973 and not need to worry about objects in other timezones.
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	974
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	975 Example \class{tzinfo} classes:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	976
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	977 \verbatiminput{tzinfo-examples.py}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	978
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	979 Note that there are unavoidable subtleties twice per year in a tzinfo
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	980 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	981 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	982 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	983 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	984
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	985 \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	986 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	987 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	988 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	989
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	990 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	991
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	992 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	993 \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	994
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	995 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	996 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	997 day, so \code{astimezone(Eastern)} won't deliver a result with
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	998 \code{hour==2} on the
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	999 day DST begins. How an Eastern instance chooses to interpret 2:MM on
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1000 that day is its business. The example Eastern implementation above
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1001 chose to
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	1002 consider it as a time in EDT, simply because it "looks like it's
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1003 after 2:00", and so synonymous with the EST 1:MM times on that day.
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1004 Your Eastern class may wish, for example, to raise an exception instead
27089 a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1005 when it sees a 2:MM time on the day EDT begins.
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	1006
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1007 When DST ends (the "end" line), there's a potentially worse problem:
27089 a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1008 there's an hour that can't be spelled unambiguously in local wall time, the
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	1009 hour beginning at the moment DST ends. In this example, that's times of
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1010 the form 6:MM UTC on the day daylight time ends. The local wall clock
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1011 leaps from 1:59 (daylight time) back to 1:00 (standard time) again.
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1012 1:MM is taken as daylight time (it's "before 2:00"), so maps to 5:MM UTC.
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1013 2:MM is taken as standard time (it's "after 2:00"), so maps to 7:MM UTC.
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1014 There is no local time that maps to 6:MM UTC on this day.
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1015
27089 a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1016 Just as the wall clock does, \code{astimezone(Eastern)} maps both UTC
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1017 hours 5:MM
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	1018 and 6:MM to Eastern hour 1:MM on this day. However, this result is
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1019 ambiguous (there's no way for Eastern to know which repetition of 1:MM
27089 a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1020 is intended). Applications that can't bear such ambiguity
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1021 should avoid using hybrid tzinfo classes; there are no
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	1022 ambiguities when using UTC, or any other fixed-offset tzinfo subclass
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1023 (such as a class representing only EST (fixed offset -5 hours), or only
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1024 EDT (fixed offset -4 hours)).
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1025
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1026
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	1027 \subsection{\class{timetz} Objects \label{datetime-timetz}}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1028
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1029 A time object represents a (local) time of day, independent of any
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1030 particular day, and subject to adjustment via a \class{tzinfo} object.
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1031
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1032 Constructor:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1033
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	1034 \begin{classdesc}{time}{hour=0, minute=0, second=0, microsecond=0,
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	1035 tzinfo=None}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1036 All arguments are optional. \var{tzinfo} may be \code{None}, or
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1037 an instance of a \class{tzinfo} subclass. The remaining arguments
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1038 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	1039
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	1040 \begin{itemize}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	1041 \item \code{0 <= \var{hour} < 24}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	1042 \item \code{0 <= \var{minute} < 60}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	1043 \item \code{0 <= \var{second} < 60}
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	1044 \item \code{0 <= \var{microsecond} < 1000000}.
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	1045 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1046
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1047 If an argument outside those ranges is given,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1048 \exception{ValueError} is raised.
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	1049 \end{classdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1050
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1051 Class attributes:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1052
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1053 \begin{memberdesc}{min}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1054 The earliest representable time, \code{timetz(0, 0, 0, 0)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1055 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1056
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1057 \begin{memberdesc}{max}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1058 The latest representable time, \code{timetz(23, 59, 59, 999999)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1059 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1060
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1061 \begin{memberdesc}{resolution}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1062 The smallest possible difference between non-equal \class{timetz}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1063 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	1064 arithmetic on \class{timetz} objects is not supported.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1065 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1066
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1067 Instance attributes (read-only):
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1068
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1069 \begin{memberdesc}{hour}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1070 In \code{range(24)}.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1071 \end{memberdesc}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1072
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1073 \begin{memberdesc}{minute}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1074 In \code{range(60)}.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1075 \end{memberdesc}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1076
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1077 \begin{memberdesc}{second}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1078 In \code{range(60)}.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1079 \end{memberdesc}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1080
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1081 \begin{memberdesc}{microsecond}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1082 In \code{range(1000000)}.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1083 \end{memberdesc}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1084
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1085 \begin{memberdesc}{tzinfo}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1086 The object passed as the tzinfo argument to the \class{timetz}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1087 constructor, or \code{None} if none was passed.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1088 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1089
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1090 Supported operations:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1091
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1092 \begin{itemize}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1093 \item
26807 2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1094 comparison of \class{timetz} to \class{time} or \class{timetz},
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1095 where \var{a} is considered less than \var{b} when \var{a} precedes
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	1096 \var{b} in time. If one comparand is naive and the other is aware,
26807 2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1097 \exception{TypeError} is raised. If both comparands are aware, and
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1098 have the same \member{tzinfo} member, the common \member{tzinfo}
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1099 member is ignored and the base times are compared. If both
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1100 comparands are aware and have different \member{tzinfo} members,
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1101 the comparands are first adjusted by subtracting their UTC offsets
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1102 (obtained from \code{self.utcoffset()}).
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1103
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1104 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1105 hash, use as dict key
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1106
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1107 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1108 pickling
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1109
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1110 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1111 in Boolean contexts, a \class{timetz} object is considered to be
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1112 true if and only if, after converting it to minutes and
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1113 subtracting \method{utcoffset()} (or \code{0} if that's
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1114 \code{None}), the result is non-zero.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1115 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1116
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1117 Instance methods:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1118
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1119 \begin{methoddesc}{replace}(hour=, minute=, second=, microsecond=, tzinfo=)
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1120 Return a \class{timetz} with the same value, except for those fields given
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1121 new values by whichever keyword arguments are specified. Note that
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1122 \code{tzinfo=None} can be specified to create a naive \class{timetz} from an
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1123 aware \class{timetz}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1124 \end{methoddesc}
26773 0f1405ace437 Implemented .replace() methods for date, datetime, datetimetz, time and Tim Peters <tim.peters@gmail.com> parents: 26765 diff changeset	1125
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1126 \begin{methoddesc}{isoformat}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1127 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	1128 HH:MM:SS.mmmmmm
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1129 or, if self.microsecond is 0,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1130 HH:MM:SS
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1131 If \method{utcoffset()} does not return \code{None}, a 6-character
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1132 string is appended, giving the UTC offset in (signed) hours and
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1133 minutes:
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1134 HH:MM:SS.mmmmmm+HH:MM
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1135 or, if self.microsecond is 0,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1136 HH:MM:SS+HH:MM
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1137 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1138
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1139 \begin{methoddesc}{__str__}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1140 For a \class{timetz} \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	1141 \code{\var{t}.isoformat()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1142 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1143
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1144 \begin{methoddesc}{strftime}{format}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1145 Return a string representing the time, controlled by an explicit
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1146 format string. See the section on \method{strftime()} behavior.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1147 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1148
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1149 \begin{methoddesc}{utcoffset}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1150 If \member{tzinfo} is \code{None}, returns \code{None}, else
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1151 \code{tzinfo.utcoffset(self)} converted to a \class{timedelta}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1152 object.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1153 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1154
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1155 \begin{methoddesc}{tzname}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1156 If \member{tzinfo} is \code{None}, returns \code{None}, else
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1157 \code{tzinfo.tzname(self)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1158 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1159
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1160 \begin{methoddesc}{dst}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1161 If \member{tzinfo} is \code{None}, returns \code{None}, else
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1162 \code{tzinfo.dst(self)} converted to a \class{timedelta} object.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1163 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1164
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1165
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1166
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	1167 \subsection{ \class{datetimetz} Objects \label{datetime-datetimetz}}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1168
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1169 \begin{notice}[warning]
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1170 I think this is \emph{still} missing some methods from the
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1171 Python implementation.
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1172 \end{notice}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1173
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1174 A \class{datetimetz} object is a single object containing all the information
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1175 from a \class{date} object and a \class{timetz} object.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1176
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1177 Constructor:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1178
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	1179 \begin{classdesc}{datetimetz}{year, month, day,
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	1180 hour=0, minute=0, second=0, microsecond=0,
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	1181 tzinfo=None}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1182 The year, month and day arguments are required. \var{tzinfo} may
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1183 be \code{None}, or an instance of a \class{tzinfo} subclass. The
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1184 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	1185
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1186 \begin{itemize}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1187 \item \code{MINYEAR <= \var{year} <= MAXYEAR}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1188 \item \code{1 <= \var{month} <= 12}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1189 \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	1190 \item \code{0 <= \var{hour} < 24}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1191 \item \code{0 <= \var{minute} < 60}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1192 \item \code{0 <= \var{second} < 60}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1193 \item \code{0 <= \var{microsecond} < 1000000}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1194 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1195
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1196 If an argument outside those ranges is given,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1197 \exception{ValueError} is raised.
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	1198 \end{classdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1199
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1200 Other constructors (class methods):
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1201
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1202 \begin{funcdesc}{today}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1203 \methodline{utcnow}{}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1204 \methodline{utcfromtimestamp}{timestamp}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1205 \methodline{fromordinal}{ordinal}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1206 These are the same as the \class{datetime} class methods of the
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1207 same names, except that they construct a \class{datetimetz}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1208 object, with tzinfo \code{None}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1209 \end{funcdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1210
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1211 \begin{funcdesc}{now}{\optional{tzinfo=None}}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1212 \methodline{fromtimestamp}{timestamp\optional{, tzinfo=None}}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1213 These are the same as the \class{datetime} class methods of the
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1214 same names, except that they accept an additional, optional tzinfo
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1215 argument, and construct a \class{datetimetz} object with that
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1216 \class{tzinfo} object attached.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1217 \end{funcdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1218
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1219 \begin{funcdesc}{combine}{date, time}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1220 This is the same as \method{datetime.combine()}, except that it
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1221 constructs a \class{datetimetz} object, and, if the time object is
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1222 of type timetz, the \class{datetimetz} object has the same
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1223 \class{tzinfo} object as the time object.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1224 \end{funcdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1225
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1226 Class attributes:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1227
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1228 \begin{memberdesc}{min}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1229 The earliest representable \class{datetimetz},
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1230 \code{datetimetz(MINYEAR, 1, 1)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1231 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1232
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1233 \begin{memberdesc}{max}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1234 The latest representable \class{datetime},
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1235 \code{datetimetz(MAXYEAR, 12, 31, 23, 59, 59, 999999)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1236 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1237
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1238 \begin{memberdesc}{resolution}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1239 The smallest possible difference between non-equal \class{datetimetz}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1240 objects, \code{timedelta(microseconds=1)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1241 \end{memberdesc}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1242
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1243 Instance attributes, all read-only:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1244
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1245 \begin{memberdesc}{year}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1246 Between \constant{MINYEAR} and \constant{MAXYEAR}, inclusive.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1247 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1248
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1249 \begin{memberdesc}{month}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1250 Between 1 and 12 inclusive
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1251 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1252
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1253 \begin{memberdesc}{day}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1254 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	1255 year.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1256 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1257
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1258 \begin{memberdesc}{hour}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1259 In \code{range(24)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1260 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1261
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1262 \begin{memberdesc}{minute}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1263 In \code{range(60)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1264 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1265
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1266 \begin{memberdesc}{second}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1267 In \code{range(60)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1268 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1269
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1270 \begin{memberdesc}{microsecond}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1271 In \code{range(1000000)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1272 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1273
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1274 \begin{memberdesc}{tzinfo}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1275 The object passed as the \var{tzinfo} argument to the
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1276 \class{datetimetz} constructor, or \code{None} if none was passed.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1277 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1278
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1279 Supported operations:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1280
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1281 \begin{itemize}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1282 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1283 datetimetz1 + timedelta -> datetimetz2
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1284 timedelta + datetimetz1 -> datetimetz2
26807 2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1285
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1286 The same as addition of \class{datetime} objects, except that
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1287 datetimetz2.tzinfo is set to datetimetz1.tzinfo.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1288
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1289 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1290 datetimetz1 - timedelta -> datetimetz2
26807 2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1291
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1292 The same as addition of \class{datetime} objects, except that
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1293 datetimetz2.tzinfo is set to datetimetz1.tzinfo.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1294
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1295 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1296 aware_datetimetz1 - aware_datetimetz2 -> timedelta
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	1297 naive_datetimetz1 - naive_datetimetz2 -> timedelta
6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	1298 naive_datetimetz1 - datetime2 -> timedelta
6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	1299 datetime1 - naive_datetimetz2 -> timedelta
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1300
26807 2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1301 Subtraction of a \class{datetime} or \class{datetimetz}, from a
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1302 \class{datetime} or \class{datetimetz}, is defined only if both
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	1303 operands are naive, or if both are aware. If one is aware and the
6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	1304 other is naive, \exception{TypeError} is raised.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1305
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	1306 If both are naive, or both are aware and have the same \member{tzinfo}
26807 2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1307 member, subtraction acts as for \class{datetime} subtraction.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1308
26807 2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1309 If both are aware and have different \member{tzinfo} members,
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1310 \code{a-b} acts as if \var{a} and \var{b} were first converted to UTC
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1311 datetimes (by subtracting \code{a.utcoffset()} minutes from \var{a},
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1312 and \code{b.utcoffset()} minutes from \var{b}), and then doing
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1313 \class{datetime} subtraction, except that the implementation never
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1314 overflows.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1315
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1316 \item
26807 2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1317 comparison of \class{datetimetz} to \class{datetime} or
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1318 \class{datetimetz}, where \var{a} is considered less than \var{b}
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1319 when \var{a} precedes \var{b} in time. If one comparand is naive and
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1320 the other is aware, \exception{TypeError} is raised. If both
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1321 comparands are aware, and have the same \member{tzinfo} member,
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1322 the common \member{tzinfo} member is ignored and the base datetimes
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1323 are compared. If both comparands are aware and have different
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1324 \member{tzinfo} members, the comparands are first adjusted by
2319d13d54f5 Make comparison and subtraction of aware objects ignore tzinfo if the Tim Peters <tim.peters@gmail.com> parents: 26792 diff changeset	1325 subtracting their UTC offsets (obtained from \code{self.utcoffset()}).
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1326
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1327 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1328 hash, use as dict key
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1329
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1330 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1331 efficient pickling
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1332
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1333 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1334 in Boolean contexts, all \class{datetimetz} objects are considered to be
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1335 true
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1336 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1337
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1338 Instance methods:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1339
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1340 \begin{methoddesc}{date}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1341 \methodline{time}{}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1342 \methodline{toordinal}{}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1343 \methodline{weekday}{}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1344 \methodline{isoweekday}{}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1345 \methodline{isocalendar}{}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1346 \methodline{ctime}{}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1347 \methodline{__str__}{}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1348 \methodline{strftime}{format}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1349 These are the same as the \class{datetime} methods of the same names.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1350 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1351
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1352 \begin{methoddesc}{timetz}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1353 Return \class{timetz} object with same hour, minute, second, microsecond,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1354 and tzinfo.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1355 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1356
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1357 \begin{methoddesc}{replace}{year=, month=, day=, hour=, minute=, second=,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1358 microsecond=, tzinfo=}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1359 Return a datetimetz with the same value, except for those fields given
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1360 new values by whichever keyword arguments are specified. Note that
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1361 \code{tzinfo=None} can be specified to create a naive datetimetz from
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1362 an aware datetimetz.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1363 \end{methoddesc}
26773 0f1405ace437 Implemented .replace() methods for date, datetime, datetimetz, time and Tim Peters <tim.peters@gmail.com> parents: 26765 diff changeset	1364
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1365 \begin{methoddesc}{astimezone}{tz}
27089 a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1366 Return a \class{datetimetz} object with new \membar{tzinfo} member
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1367 \var{tz}.
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1368 \var{tz} must be \code{None}, or an instance of a \class{tzinfo} subclass.
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1369 If \var{tz} is \code{None}, \var{self} is naive,
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1370 \code{tz.utcoffset(self)} returns \code{None},
27089 a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1371 or \code{self.tzinfo}\ is \var{tz},
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1372 \code{self.astimezone(tz)} is equivalent to
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1373 \code{self.replace(tzinfo=tz)}: a new timezone object is attached
27089 a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1374 without any conversion of date or time fields. Else \code{self.tzinfo}
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1375 and \var{tz} must implement the \method{utcoffset()} and \method{dst()}
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1376 \class{tzinfo} methods, and the date and time fields are adjusted so
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1377 that the result is local time in time zone \var{tz}, representing the
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1378 same UTC time as \var{self}: after \code{astz = dt.astimezone(tz)},
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1379 \code{astz - astz.utcoffset()} will usually have the same date and time
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1380 members as \code{dt - dt.utcoffset()}. The discussion of class
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1381 \class{tzinfo} explains the cases at Daylight Saving Time
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1382 transition boundaries where this cannot be achieved (an issue only if
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1383 \var{tz} models both standard and daylight time).
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1384 \end{methoddesc}
26792 816b8ddccfe1 Implemented datetime.astimezone() and datetimetz.astimezone(). Tim Peters <tim.peters@gmail.com> parents: 26787 diff changeset	1385
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1386 \begin{methoddesc}{utcoffset}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1387 If \member{tzinfo} is \code{None}, returns \code{None}, else
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1388 \code{tzinfo.utcoffset(self)} converted to a \class{timedelta}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1389 object.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1390 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1391
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1392 \begin{methoddesc}{tzname}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1393 If \member{tzinfo} is \code{None}, returns \code{None}, else
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1394 returns \code{tzinfo.tzname(self)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1395 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1396
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1397 \begin{methoddesc}{dst}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1398 If \member{tzinfo} is \code{None}, returns \code{None}, else
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1399 \code{tzinfo.dst(self)} converted to a \class{timedelta}
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1400 object.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1401 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1402
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1403 \begin{methoddesc}{timetuple}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1404 Like \function{datetime.timetuple()}, but sets the
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1405 \member{tm_isdst} flag according to the \method{dst()} method: if
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1406 \method{dst()} returns \code{None}, \member{tm_isdst} is set to
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1407 \code{-1}; else if \method{dst()} returns a non-zero value,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1408 \member{tm_isdst} is set to \code{1}; else \code{tm_isdst} is set
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1409 to \code{0}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1410 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1411
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1412 \begin{methoddesc}{utctimetuple}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1413 If \class{datetimetz} instance \var{d} is naive, this is the same as
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1414 \code{\var{d}.timetuple()} except that \member{tm_isdst} is forced to 0
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1415 regardless of what \code{d.dst()} returns. DST is never in effect
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1416 for a UTC time.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1417
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1418 If \var{d} is aware, \var{d} is normalized to UTC time, by subtracting
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1419 \code{\var{d}.utcoffset()} minutes, and a timetuple for the
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1420 normalized time is returned. \member{tm_isdst} is forced to 0.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1421 Note that the result's \member{tm_year} field may be
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1422 \constant{MINYEAR}-1 or \constant{MAXYEAR}+1, if \var{d}.year was
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1423 \code{MINYEAR} or \code{MAXYEAR} and UTC adjustment spills over a
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1424 year boundary.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1425 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1426
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1427 \begin{methoddesc}{isoformat}{sep='T'}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1428 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	1429 YYYY-MM-DDTHH:MM:SS.mmmmmm
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1430 or, if \member{microsecond} is 0,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1431 YYYY-MM-DDTHH:MM:SS
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1432
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1433 If \method{utcoffset()} does not return \code{None}, a 6-character
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1434 string is appended, giving the UTC offset in (signed) hours and
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1435 minutes:
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1436 YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1437 or, if \member{microsecond} is 0
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1438 YYYY-MM-DDTHH:MM:SS+HH:MM
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1439
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1440 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	1441 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	1442 of the result. For example,
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1443
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1444 \begin{verbatim}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1445 >>> from datetime import *
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1446 >>> class TZ(tzinfo):
27034 dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	1447 ... def utcoffset(self, dt): return timedelta(minutes=-399)
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1448 ...
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1449 >>> datetimetz(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1450 '2002-12-25 00:00:00-06:39'
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1451 \end{verbatim}
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1452 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1453
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1454 \code{str(\var{d})} is equivalent to \code{\var{d}.isoformat(' ')}.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1455
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1456
26765 095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1457 \subsection{\method{strftime()} Behavior}
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1458
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1459 \class{date}, \class{datetime}, \class{datetimetz}, \class{time},
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1460 and \class{timetz} objects all support a \code{strftime(\var{format})}
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1461 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	1462 an explicit format string. Broadly speaking,
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1463 \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	1464 acts like the \refmodule{time} module's
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1465 \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	1466 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	1467
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1468 For \class{time} and \class{timetz} objects, the format codes for
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1469 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	1470 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	1471 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	1472
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1473 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	1474 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	1475 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	1476
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	1477 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	1478 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	1479
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1480 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	1481
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1482 \begin{itemize}
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1483 \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	1484 \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	1485 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	1486 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	1487 number of UTC offset minutes. For example, if
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1488 \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	1489 \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	1490
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1491 \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	1492 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	1493 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	1494 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	1495 \end{itemize}
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1496
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1497 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	1498 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	1499 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	1500 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	1501 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	1502 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	1503 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	1504
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1505 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	1506 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	1507 cannot be used.
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1508
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1509
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1510 \begin{comment}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1511
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1512 \subsection{C API}
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1513
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1514 Struct typedefs:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1515
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1516 PyDateTime_Date
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1517 PyDateTime_DateTime
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1518 PyDateTime_DateTimeTZ
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1519 PyDateTime_Time
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1520 PyDateTime_TimeTZ
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1521 PyDateTime_Delta
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1522 PyDateTime_TZInfo
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1523
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1524 Type-check macros:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1525
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1526 PyDate_Check(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1527 PyDate_CheckExact(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1528
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1529 PyDateTime_Check(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1530 PyDateTime_CheckExact(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1531
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1532 PyDateTimeTZ_Check(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1533 PyDateTimeTZ_CheckExact(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1534
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1535 PyTime_Check(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1536 PyTime_CheckExact(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1537
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1538 PyTimeTZ_Check(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1539 PyTimeTZ_CheckExact(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1540
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1541 PyDelta_Check(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1542 PyDelta_CheckExact(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1543
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1544 PyTZInfo_Check(op)
26962 b9c462d23f3c Add markup for time object. Raymond Hettinger <python@rcn.com> parents: 26958 diff changeset	1545 PyTZInfo_CheckExact(op)
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1546
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1547 Accessor macros:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1548
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1549 All objects are immutable, so accessors are read-only. All macros
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1550 return ints:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1551
26785 0b34f51eab4e tzinfo.{utcoffset,dst} can return timedelta (or integer or None). Tim Peters <tim.peters@gmail.com> parents: 26773 diff changeset	1552 For \class{date}, \class{datetime}, and \class{datetimetz} instances:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1553 PyDateTime_GET_YEAR(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1554 PyDateTime_GET_MONTH(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1555 PyDateTime_GET_DAY(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1556
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1557 For \class{datetime} and \class{datetimetz} instances:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1558 PyDateTime_DATE_GET_HOUR(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1559 PyDateTime_DATE_GET_MINUTE(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1560 PyDateTime_DATE_GET_SECOND(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1561 PyDateTime_DATE_GET_MICROSECOND(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1562
26785 0b34f51eab4e tzinfo.{utcoffset,dst} can return timedelta (or integer or None). Tim Peters <tim.peters@gmail.com> parents: 26773 diff changeset	1563 For \class{time} and \class{timetz} instances:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1564 PyDateTime_TIME_GET_HOUR(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1565 PyDateTime_TIME_GET_MINUTE(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1566 PyDateTime_TIME_GET_SECOND(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1567 PyDateTime_TIME_GET_MICROSECOND(o)
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1568
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1569 \end{comment}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libdatetime.tex @ 27089:a123793ca193 legacy-trunk