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

annotate Doc/lib/libdatetime.tex @ 32527:0da660e05e69 legacy-trunk

"#if WITH_THREAD" is incorrect; must be #ifdef instead; WITH_THREAD isn't always set to an integer value when it's defined.

author	Tim Peters <tim.peters@gmail.com>
date	Wed, 07 Jul 2004 20:42:07 +0000
parents	d6d1efdcc5fd
children	a8de2195efd6

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

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libdatetime.tex @ 32527:0da660e05e69 legacy-trunk