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

annotate Doc/lib/libdatetime.tex @ 27998:e27f58a50737 legacy-trunk

SF bug #690377: Dud footnote reference in distutils docs

author	Raymond Hettinger <python@rcn.com>
date	Fri, 21 Feb 2003 02:47:09 +0000
parents	fc88174c0c0a
children	ab7dc538f6f7

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
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	109 \code{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
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	127 \begin{classdesc}{timedelta}{days=0, seconds=0, microseconds=0,
e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	128 milliseconds=0, minutes=0, hours=0, weeks=0}
26970 4448ff8b3239 Use funcdesc instead of classdesc to be consistent with out sections. Raymond Hettinger <python@rcn.com> parents: 26965 diff changeset	129
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	130 All arguments are optional. Arguments may be ints, longs, or floats,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	131 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}.
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	212 Afterwards \var{t1} == \var{t2} - \var{t3} and \var{t2} == \var{t1} + \var{t3} are
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	213 true.
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
27185 c798613a8765 Various minor edits Andrew M. Kuchling <amk@amk.ca> parents: 27184 diff changeset	355 % XXX rewrite to be a table
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	356 \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	357 \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	358 {\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	359 \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	360
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	361
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	362 \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	363 {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	364 == \var{date1}}. (2)}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	365
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	366 \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	367 {(3)}
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	368
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	369 \lineii{\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	370 {\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	371 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	372
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	373 \end{tableii}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	374
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	375 Notes:
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	376 \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	377
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	378 \item[(1)]
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	379 \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	380 > 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	381 \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	382 \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	383 \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	384 \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	385 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	386 \constant{MAXYEAR}.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	387
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	388 \item[(2)]
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	389 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	390 (-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	391 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	392 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	393
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	394 \item[(3)]
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	395 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	396 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	397 after.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	398
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	399 \item[(4)]
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	400 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	401 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	402 \var{date2}.toordinal()}.
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	403 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	404 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	405 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	406 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	407 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	408 \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	409 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	410 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	411 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	412 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	413 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	414
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	415 \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	416
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	417
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	418 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	419 \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	420
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	421 Instance methods:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	422
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	423 \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	424 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	425 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	426 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	427 \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	428 \end{methoddesc}
26773 0f1405ace437 Implemented .replace() methods for date, datetime, datetimetz, time and Tim Peters <tim.peters@gmail.com> parents: 26765 diff changeset	429
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	430 \begin{methoddesc}{timetuple}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	431 Return a 9-element tuple of the form returned by
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	432 \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	433 0, and the DST flag is -1.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	434 \code{\var{d}.timetuple()} is equivalent to
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	435 \code{(\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	436 0, 0, 0,
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	437 \var{d}.weekday(),
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	438 \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	439 -1)}
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	440 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	441
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	442 \begin{methoddesc}{toordinal}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	443 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	444 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	445 \code{date.fromordinal(\var{d}.toordinal()) == \var{d}}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	446 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	447
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	448 \begin{methoddesc}{weekday}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	449 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	450 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	451 Wednesday.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	452 See also \method{isoweekday()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	453 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	454
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	455 \begin{methoddesc}{isoweekday}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	456 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	457 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	458 Wednesday.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	459 See also \method{weekday()}, \method{isocalendar()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	460 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	461
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	462 \begin{methoddesc}{isocalendar}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	463 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	464
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	465 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	466 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	467 for a good explanation.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	468
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	469 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	470 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	471 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	472 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	473 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	474
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	475 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	476 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	477 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	478 \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	479 and
c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	480 \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	481 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	482
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	483 \begin{methoddesc}{isoformat}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	484 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	485 '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	486 \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	487 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	488
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	489 \begin{methoddesc}{__str__}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	490 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	491 \code{\var{d}.isoformat()}.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	492 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	493
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	494 \begin{methoddesc}{ctime}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	495 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	496 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	497 \code{\var{d}.ctime()} is equivalent to
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	498 \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	499 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	500 (which \function{time.ctime()} invokes, but which
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	501 \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	502 \end{methoddesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	503
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	504 \begin{methoddesc}{strftime}{format}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	505 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	506 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	507 will see 0 values.
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	508 See the section on \method{strftime()} behavior.
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	509 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	510
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	511
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	512 \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	513
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	514 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	515 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	516 \class{date} object, \class{datetime} assumes the current Gregorian
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	517 calendar extended in both directions; like a time object,
37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	518 \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	519 day.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	520
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	521 Constructor:
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	522
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	523 \begin{classdesc}{datetime}{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	524 hour=0, minute=0, second=0, microsecond=0,
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	525 tzinfo=None}
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
27350 22992fa51831 Reimplemented datetime.now() to be useful. Tim Peters <tim.peters@gmail.com> parents: 27339 diff changeset	553 \begin{methoddesc}{now(tz=None)}{}
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
27351 bbf14185bf1e SF bug 660872: datetimetz constructors behave counterintuitively (2.3a1). Tim Peters <tim.peters@gmail.com> parents: 27350 diff changeset	575 \begin{methoddesc}{fromtimestamp}{timestamp, tz=None}
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
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	783 \begin{methoddesc}{replace}{year=, month=, day=, hour=, minute=, second=,
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	784 microsecond=, tzinfo=}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	785 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	786 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	787 \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	788 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	789 \end{methoddesc}
26773 0f1405ace437 Implemented .replace() methods for date, datetime, datetimetz, time and Tim Peters <tim.peters@gmail.com> parents: 26765 diff changeset	790
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	791 \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	792 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	793 \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	794 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	795
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	796 \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	797 \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	798 \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	799 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	800 \code{None}).
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	801
27704 c8c7816d3a2d Markup fixes; in particular, the tables are now reasonable width Andrew M. Kuchling <amk@amk.ca> parents: 27526 diff changeset	802 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	803 \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	804 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	805 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	806 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	807 \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	808 \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	809 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	810 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	811 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	812 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	813
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	814 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	815 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	816 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	817 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	818 \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	819 \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	820
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	821 Note that the default \method{tzinfo.fromutc()} method can be overridden
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	822 in a \class{tzinfo} subclass to effect the result returned by
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	823 \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	824 acts like:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	825
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	826 \begin{verbatim}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	827 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	828 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	829 return self
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	830 # 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	831 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	832 # 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	833 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	834 \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	835 \end{methoddesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	836
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	837 \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	838 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	839 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	840 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	841 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	842 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	843 \end{methoddesc}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	844
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	845 \begin{methoddesc}{dst}{}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	846 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	847 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	848 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	849 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	850 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	851 \end{methoddesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	852
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	853 \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	854 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	855 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	856 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	857 a string object,
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	858 \end{methoddesc}
26792 816b8ddccfe1 Implemented datetime.astimezone() and datetimetz.astimezone(). Tim Peters <tim.peters@gmail.com> parents: 26787 diff changeset	859
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	860 \begin{methoddesc}{timetuple}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	861 Return a 9-element tuple of the form returned by
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	862 \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	863 \code{\var{d}.timetuple()} is equivalent to
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	864 \code{(\var{d}.year, \var{d}.month, \var{d}.day,
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	865 \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	866 \var{d}.weekday(),
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	867 \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	868 dst)}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	869 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	870 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	871 \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	872 \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	873 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	874 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	875 \end{methoddesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	876
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	877 \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	878 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	879 \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	880 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	881 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	882
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	883 If \var{d} is aware, \var{d} is normalized to UTC time, by subtracting
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	884 \code{\var{d}.utcoffset()}, and a timetuple for the
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	885 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	886 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	887 \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	888 \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	889 year boundary.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	890 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	891
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	892 \begin{methoddesc}{toordinal}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	893 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	894 \code{self.date().toordinal()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	895 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	896
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	897 \begin{methoddesc}{weekday}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	898 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	899 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	900 See also \method{isoweekday()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	901 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	902
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	903 \begin{methoddesc}{isoweekday}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	904 Return the day of the week as an integer, where Monday is 1 and
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	905 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	906 See also \method{weekday()}, \method{isocalendar()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	907 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	908
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	909 \begin{methoddesc}{isocalendar}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	910 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	911 same as \code{self.date().isocalendar()}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	912 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	913
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	914 \begin{methoddesc}{isoformat}{sep='T'}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	915 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	916 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	917 or, if \member{microsecond} is 0,
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	918 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	919
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	920 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	921 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	922 minutes:
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	923 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	924 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	925 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	926
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	927 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	928 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	929 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	930
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	931 \begin{verbatim}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	932 >>> 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	933 >>> 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	934 ... 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	935 ...
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	936 >>> 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	937 '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	938 \end{verbatim}
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	939 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	940
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	941 \begin{methoddesc}{__str__}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	942 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	943 equivalent to \code{\var{d}.isoformat(' ')}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	944 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	945
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	946 \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	947 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	948 \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	949 '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	950 \code{d.ctime()} is equivalent to
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	951 \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	952 the native C \cfunction{ctime()} function (which
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	953 \function{time.ctime()} invokes, but which
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	954 \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	955 standard.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	956 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	957
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	958 \begin{methoddesc}{strftime}{format}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	959 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	960 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	961 behavior.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	962 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	963
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	964
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	965 \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	966
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	967 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	968 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	969
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	970 \begin{classdesc}{time}{hour=0, minute=0, second=0, microsecond=0,
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	971 tzinfo=None}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	972 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	973 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	974 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	975
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	976 \begin{itemize}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	977 \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	978 \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	979 \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	980 \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	981 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	982
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	983 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	984 \exception{ValueError} is raised.
26984 e02daf6307fc - use classdesc where we can (for better indexing) Fred Drake <fdrake@acm.org> parents: 26978 diff changeset	985 \end{classdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	986
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	987 Class attributes:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	988
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	989 \begin{memberdesc}{min}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	990 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	991 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	992
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	993 \begin{memberdesc}{max}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	994 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	995 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	996
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	997 \begin{memberdesc}{resolution}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	998 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	999 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	1000 arithmetic on \class{time} objects is not supported.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1001 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1002
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1003 Instance attributes (read-only):
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1004
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1005 \begin{memberdesc}{hour}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1006 In \code{range(24)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1007 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1008
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	1009 \begin{memberdesc}{minute}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1010 In \code{range(60)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1011 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1012
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	1013 \begin{memberdesc}{second}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1014 In \code{range(60)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1015 \end{memberdesc}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1016
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	1017 \begin{memberdesc}{microsecond}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1018 In \code{range(1000000)}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1019 \end{memberdesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1020
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1021 \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	1022 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	1023 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	1024 \end{memberdesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1025
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1026 Supported operations:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1027
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1028 \begin{itemize}
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1029 \item
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1030 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	1031 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	1032 \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	1033 \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	1034 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	1035 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	1036 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	1037 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	1038 (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	1039 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	1040 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	1041 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	1042 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	1043 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	1044
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1045 \item
49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1046 hash, use as dict key
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 efficient pickling
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
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1052 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	1053 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	1054 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	1055 \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	1056 \end{itemize}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1057
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1058 Instance methods:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1059
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1060 \begin{methoddesc}{replace}(hour=, minute=, second=, microsecond=, tzinfo=)
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1061 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	1062 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	1063 \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	1064 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	1065 \end{methoddesc}
26773 0f1405ace437 Implemented .replace() methods for date, datetime, datetimetz, time and Tim Peters <tim.peters@gmail.com> parents: 26765 diff changeset	1066
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1067 \begin{methoddesc}{isoformat}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1068 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	1069 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	1070 or, if self.microsecond is 0,
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1071 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	1072 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	1073 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	1074 minutes:
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1075 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	1076 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	1077 HH:MM:SS+HH:MM
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1078 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1079
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1080 \begin{methoddesc}{__str__}{}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1081 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	1082 \code{\var{t}.isoformat()}.
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}{strftime}{format}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1086 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	1087 format string. See the section on \method{strftime()} behavior.
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
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1090 \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	1091 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	1092 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	1093 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	1094 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	1095 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	1096 \end{methoddesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1097
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1098 \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	1099 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	1100 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	1101 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	1102 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	1103 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	1104 \end{methoddesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1105
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1106 \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	1107 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	1108 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	1109 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	1110 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	1111 \end{methoddesc}
07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1112
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1113
26864 83f8bd6ae811 Added markup upto line 233. Raymond Hettinger <python@rcn.com> parents: 26846 diff changeset	1114 \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	1115
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1116 \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	1117 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	1118 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	1119 \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	1120 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	1121 subclasses of \class{tzinfo}.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1122
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1123 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	1124 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	1125 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	1126 \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	1127 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	1128 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	1129
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	1130 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	1131 \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	1132 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	1133 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	1134
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1135 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	1136 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	1137 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	1138 implement all of them.
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1139
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	1140 \begin{methoddesc}{utcoffset}{self, dt}
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1141 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	1142 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	1143 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	1144 \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	1145 \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	1146 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	1147 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	1148 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	1149 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	1150 \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	1151
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	1152 \begin{verbatim}
27008 4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	1153 return CONSTANT # fixed-offset class
26978 35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1154 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	1155 \end{verbatim}
27034 dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	1156
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	1157 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	1158 \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	1159
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1160 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	1161 \exception{NotImplementedError}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1162 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1163
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	1164 \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	1165 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	1166 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	1167 \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	1168 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	1169 \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	1170 Note that DST offset, if applicable, has
35e5b021b774 General style conformance. Markup some unmarked constructs. Fred Drake <fdrake@acm.org> parents: 26970 diff changeset	1171 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	1172 \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	1173 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	1174 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	1175 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	1176 \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	1177 \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	1178 DST changes when crossing time zones.
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	1179
4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	1180 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	1181 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	1182
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1183 \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	1184
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1185 must return the same result for every \class{datetime} \var{dt}
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1186 with \code{\var{dt}.tzinfo==\var{tz}} For sane \class{tzinfo}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1187 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	1188 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	1189 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	1190 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	1191 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	1192 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	1193 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	1194 regardless.
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1195
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1196 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	1197 of these two:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1198
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1199 \begin{verbatim}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1200 return timedelta(0) # a fixed-offset class: doesn't account for DST
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1201
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1202 or
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 # Code to set dston and dstoff to the time zone's DST transition
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1205 # times based on the input dt.year, and expressed in standard local
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1206 # time. Then
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1207
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1208 if dston <= dt.replace(tzinfo=None) < dstoff:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1209 return timedelta(hours=1)
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1210 else:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1211 return timedelta(0)
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1212 \end{verbatim}
27008 4579e83c663b A quicker astimezone() implementation, rehabilitating an earlier Tim Peters <tim.peters@gmail.com> parents: 26984 diff changeset	1213
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1214 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	1215 \exception{NotImplementedError}.
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1216 \end{methoddesc}
efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1217
27034 dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	1218 \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	1219 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	1220 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	1221 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	1222 \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	1223 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	1224 "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	1225 \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	1226 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	1227 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	1228 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	1229 accounting for daylight time.
dc33d027645a astimezone() internals: if utcoffset() returns a duration, complain if Tim Peters <tim.peters@gmail.com> parents: 27008 diff changeset	1230
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1231 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	1232 \exception{NotImplementedError}.
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1233 \end{methoddesc}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1234
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1235 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	1236 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	1237 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	1238 \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	1239 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	1240 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	1241
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	1242 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	1243 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	1244 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	1245 \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	1246 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	1247 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	1248
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1249 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	1250 \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	1251 \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	1252 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	1253 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	1254 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	1255
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1256 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	1257 override:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1258
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1259 \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	1260 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	1261 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	1262 \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	1263 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	1264 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	1265 \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	1266
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1267 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	1268 \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	1269 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	1270 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	1271 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	1272 \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	1273 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	1274 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	1275 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	1276 \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	1277 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	1278
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1279 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	1280 implementation acts like:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1281
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1282 \begin{verbatim}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1283 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	1284 # 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	1285 dtoff = dt.utcoffset()
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1286 dtdst = dt.dst()
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1287 # 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	1288 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	1289 if delta:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1290 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	1291 dtdst = dt.dst()
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1292 # 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	1293 if dtdst:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1294 return dt + dtdst
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1295 else:
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1296 return dt
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1297 \end{verbatim}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1298 \end{methoddesc}
d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1299
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1300 Example \class{tzinfo} classes:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1301
26762 49d022b5fd64 Lots of markup changes. This is still pretty sad, but passes LaTeX Fred Drake <fdrake@acm.org> parents: 26704 diff changeset	1302 \verbatiminput{tzinfo-examples.py}
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1303
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1304 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	1305 \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	1306 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	1307 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	1308 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	1309 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	1310
64e8c6986610 A new implementation of astimezone() that does what we agreed on in all Tim Peters <tim.peters@gmail.com> parents: 27037 diff changeset	1311 \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	1312 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	1313 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	1314 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	1315
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 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	1317
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 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	1319 \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	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 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	1322 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	1323 day, so \code{astimezone(Eastern)} won't deliver a result with
a123793ca193 datetime_from_timet_and_us(): ignore leap seconds if the platform Tim Peters <tim.peters@gmail.com> parents: 27082 diff changeset	1324 \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	1325 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	1326 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	1327 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	1328
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 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	1330 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	1331 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	1332 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	1333 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	1334 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	1335 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	1336 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	1337 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	1338 \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	1339 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	1340 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	1341 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	1342
27315 efa2f8abb02c New rule for tzinfo subclasses handling both standard and daylight time: Tim Peters <tim.peters@gmail.com> parents: 27185 diff changeset	1343 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	1344 \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	1345 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	1346 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	1347 -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	1348
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1349
26765 095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1350 \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	1351
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1352 \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	1353 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	1354 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	1355 an explicit format string. Broadly speaking,
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1356 \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	1357 acts like the \refmodule{time} module's
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1358 \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	1359 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	1360
27178 07c6c2e98a1c Massive fiddling to reflect that datetimetz and timetz no longer exist. Tim Peters <tim.peters@gmail.com> parents: 27108 diff changeset	1361 For \class{time} objects, the format codes for
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1362 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	1363 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	1364 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	1365
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1366 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	1367 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	1368 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	1369
26881 6ec386b45e1f We're using strictly American spellings, so there's no diaresis over Fred Drake <fdrake@acm.org> parents: 26876 diff changeset	1370 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	1371 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	1372
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1373 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	1374
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1375 \begin{itemize}
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1376 \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	1377 \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	1378 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	1379 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	1380 number of UTC offset minutes. For example, if
26841 37ef017646c4 Mark up more text Andrew M. Kuchling <amk@amk.ca> parents: 26813 diff changeset	1381 \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	1382 \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	1383
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1384 \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	1385 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	1386 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	1387 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	1388 \end{itemize}
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1389
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1390 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	1391 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	1392 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	1393 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	1394 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	1395 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	1396 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	1397
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1398 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	1399 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	1400 cannot be used.
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1401
095440b975a1 Brought the strftime explanation into synch with the plain-text sandbox Tim Peters <tim.peters@gmail.com> parents: 26762 diff changeset	1402
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1403 \begin{comment}
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1404
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1405 \subsection{C API}
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1406
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1407 Struct typedefs:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1408
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1409 PyDateTime_Date
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1410 PyDateTime_DateTime
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1411 PyDateTime_Time
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1412 PyDateTime_Delta
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1413 PyDateTime_TZInfo
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1414
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1415 Type-check macros:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1416
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1417 PyDate_Check(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1418 PyDate_CheckExact(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1419
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1420 PyDateTime_Check(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1421 PyDateTime_CheckExact(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1422
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1423 PyTime_Check(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1424 PyTime_CheckExact(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1425
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1426 PyDelta_Check(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1427 PyDelta_CheckExact(op)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1428
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1429 PyTZInfo_Check(op)
26962 b9c462d23f3c Add markup for time object. Raymond Hettinger <python@rcn.com> parents: 26958 diff changeset	1430 PyTZInfo_CheckExact(op)
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1431
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1432 Accessor macros:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1433
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1434 All objects are immutable, so accessors are read-only. All macros
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1435 return ints:
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1436
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1437 For \class{date} and \class{datetime} instances:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1438 PyDateTime_GET_YEAR(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1439 PyDateTime_GET_MONTH(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1440 PyDateTime_GET_DAY(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1441
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1442 For \class{datetime} instances:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1443 PyDateTime_DATE_GET_HOUR(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1444 PyDateTime_DATE_GET_MINUTE(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1445 PyDateTime_DATE_GET_SECOND(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1446 PyDateTime_DATE_GET_MICROSECOND(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1447
27339 d34ef00d9da8 "Premature" doc changes, for new astimezone() rules, and the new Tim Peters <tim.peters@gmail.com> parents: 27330 diff changeset	1448 For \class{time} instances:
26704 f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1449 PyDateTime_TIME_GET_HOUR(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1450 PyDateTime_TIME_GET_MINUTE(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1451 PyDateTime_TIME_GET_SECOND(o)
f91d78e19c86 Check in current, unfinished, draft of datetime docs Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	1452 PyDateTime_TIME_GET_MICROSECOND(o)
26846 fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1453
fc5169aa41ce More markup additions Andrew M. Kuchling <amk@amk.ca> parents: 26841 diff changeset	1454 \end{comment}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libdatetime.tex @ 27998:e27f58a50737 legacy-trunk