add hg and python

1 files changed, 1441 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libdatetime.tex b/sys/src/cmd/python/Doc/lib/libdatetime.tex
new file mode 100644
index 000000000..0d2b5bb64
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libdatetime.tex
@@ -0,0 +1,1441 @@
+% XXX what order should the types be discussed in?
+
+\section{\module{datetime} ---
+         Basic date and time types}
+
+\declaremodule{builtin}{datetime}
+\modulesynopsis{Basic date and time types.}
+\moduleauthor{Tim Peters}{tim@zope.com}
+\sectionauthor{Tim Peters}{tim@zope.com}
+\sectionauthor{A.M. Kuchling}{amk@amk.ca}
+
+\versionadded{2.3}
+
+
+The \module{datetime} module supplies classes for manipulating dates
+and times in both simple and complex ways.  While date and time
+arithmetic is supported, the focus of the implementation is on
+efficient member extraction for output formatting and manipulation.
+
+There are two kinds of date and time objects: ``naive'' and ``aware''.
+This distinction refers to whether the object has any notion of time
+zone, daylight saving time, or other kind of algorithmic or political
+time adjustment.  Whether a naive \class{datetime} object represents
+Coordinated Universal Time (UTC), local time, or time in some other
+timezone is purely up to the program, just like it's up to the program
+whether a particular number represents metres, miles, or mass.  Naive
+\class{datetime} objects are easy to understand and to work with, at
+the cost of ignoring some aspects of reality.
+
+For applications requiring more, \class{datetime} and \class{time}
+objects have an optional time zone information member,
+\member{tzinfo}, that can contain an instance of a subclass of
+the abstract \class{tzinfo} class.  These \class{tzinfo} objects
+capture information about the offset from UTC time, the time zone
+name, and whether Daylight Saving Time is in effect.  Note that no
+concrete \class{tzinfo} classes are supplied by the \module{datetime}
+module.  Supporting timezones at whatever level of detail is required
+is up to the application.  The rules for time adjustment across the
+world are more political than rational, and there is no standard
+suitable for every application.
+
+The \module{datetime} module exports the following constants:
+
+\begin{datadesc}{MINYEAR}
+  The smallest year number allowed in a \class{date} or
+  \class{datetime} object.  \constant{MINYEAR}
+  is \code{1}.
+\end{datadesc}
+
+\begin{datadesc}{MAXYEAR}
+  The largest year number allowed in a \class{date} or \class{datetime}
+  object.  \constant{MAXYEAR} is \code{9999}.
+\end{datadesc}
+
+\begin{seealso}
+  \seemodule{calendar}{General calendar related functions.}
+  \seemodule{time}{Time access and conversions.}
+\end{seealso}
+
+\subsection{Available Types}
+
+\begin{classdesc*}{date}
+  An idealized naive date, assuming the current Gregorian calendar
+  always was, and always will be, in effect.
+  Attributes: \member{year}, \member{month}, and \member{day}.
+\end{classdesc*}
+
+\begin{classdesc*}{time}
+  An idealized time, independent of any particular day, assuming
+  that every day has exactly 24*60*60 seconds (there is no notion
+  of "leap seconds" here).
+  Attributes: \member{hour}, \member{minute}, \member{second},
+              \member{microsecond}, and \member{tzinfo}.
+\end{classdesc*}
+
+\begin{classdesc*}{datetime}
+  A combination of a date and a time.
+  Attributes: \member{year}, \member{month}, \member{day},
+              \member{hour}, \member{minute}, \member{second},
+              \member{microsecond}, and \member{tzinfo}.
+\end{classdesc*}
+
+\begin{classdesc*}{timedelta}
+  A duration expressing the difference between two \class{date},
+  \class{time}, or \class{datetime} instances to microsecond
+  resolution.
+\end{classdesc*}
+
+\begin{classdesc*}{tzinfo}
+  An abstract base class for time zone information objects.  These
+  are used by the  \class{datetime} and \class{time} classes to
+  provide a customizable notion of time adjustment (for example, to
+  account for time zone and/or daylight saving time).
+\end{classdesc*}
+
+Objects of these types are immutable.
+
+Objects of the \class{date} type are always naive.
+
+An object \var{d} of type \class{time} or \class{datetime} may be
+naive or aware.  \var{d} is aware if \code{\var{d}.tzinfo} is not
+\code{None} and \code{\var{d}.tzinfo.utcoffset(\var{d})} does not return
+\code{None}.  If \code{\var{d}.tzinfo} is \code{None}, or if
+\code{\var{d}.tzinfo} is not \code{None} but
+\code{\var{d}.tzinfo.utcoffset(\var{d})} returns \code{None}, \var{d}
+is naive.
+
+The distinction between naive and aware doesn't apply to
+\class{timedelta} objects.
+
+Subclass relationships:
+
+\begin{verbatim}
+object
+    timedelta
+    tzinfo
+    time
+    date
+        datetime
+\end{verbatim}
+
+\subsection{\class{timedelta} Objects \label{datetime-timedelta}}
+
+A \class{timedelta} object represents a duration, the difference
+between two dates or times.
+
+\begin{classdesc}{timedelta}{\optional{days\optional{, seconds\optional{,
+                             microseconds\optional{, milliseconds\optional{,
+                             minutes\optional{, hours\optional{, weeks}}}}}}}}
+  All arguments are optional and default to \code{0}.  Arguments may
+  be ints, longs, or floats, and may be positive or negative.
+
+  Only \var{days}, \var{seconds} and \var{microseconds} are stored
+  internally.  Arguments are converted to those units:
+
+\begin{itemize}
+  \item A millisecond is converted to 1000 microseconds.
+  \item A minute is converted to 60 seconds.
+  \item An hour is converted to 3600 seconds.
+  \item A week is converted to 7 days.
+\end{itemize}
+
+  and days, seconds and microseconds are then normalized so that the
+  representation is unique, with
+
+\begin{itemize}
+  \item \code{0 <= \var{microseconds} < 1000000}
+  \item \code{0 <= \var{seconds} < 3600*24} (the number of seconds in one day)
+  \item \code{-999999999 <= \var{days} <= 999999999}
+\end{itemize}
+
+  If any argument is a float and there are fractional microseconds,
+  the fractional microseconds left over from all arguments are combined
+  and their sum is rounded to the nearest microsecond.  If no
+  argument is a float, the conversion and normalization processes
+  are exact (no information is lost).
+
+  If the normalized value of days lies outside the indicated range,
+  \exception{OverflowError} is raised.
+
+  Note that normalization of negative values may be surprising at first.
+  For example,
+
+\begin{verbatim}
+>>> d = timedelta(microseconds=-1)
+>>> (d.days, d.seconds, d.microseconds)
+(-1, 86399, 999999)
+\end{verbatim}
+\end{classdesc}
+
+Class attributes are:
+
+\begin{memberdesc}{min}
+  The most negative \class{timedelta} object,
+  \code{timedelta(-999999999)}.
+\end{memberdesc}
+
+\begin{memberdesc}{max}
+  The most positive \class{timedelta} object,
+  \code{timedelta(days=999999999, hours=23, minutes=59, seconds=59,
+                  microseconds=999999)}.
+\end{memberdesc}
+
+\begin{memberdesc}{resolution}
+  The smallest possible difference between non-equal
+  \class{timedelta} objects, \code{timedelta(microseconds=1)}.
+\end{memberdesc}
+
+Note that, because of normalization, \code{timedelta.max} \textgreater
+\code{-timedelta.min}.  \code{-timedelta.max} is not representable as
+a \class{timedelta} object.
+
+Instance attributes (read-only):
+
+\begin{tableii}{c|l}{code}{Attribute}{Value}
+  \lineii{days}{Between -999999999 and 999999999 inclusive}
+  \lineii{seconds}{Between 0 and 86399 inclusive}
+  \lineii{microseconds}{Between 0 and 999999 inclusive}
+\end{tableii}
+
+Supported operations:
+
+% XXX this table is too wide!
+\begin{tableii}{c|l}{code}{Operation}{Result}
+  \lineii{\var{t1} = \var{t2} + \var{t3}}
+          {Sum of \var{t2} and \var{t3}.
+           Afterwards \var{t1}-\var{t2} == \var{t3} and \var{t1}-\var{t3}
+           == \var{t2} are true.
+          (1)}
+  \lineii{\var{t1} = \var{t2} - \var{t3}}
+          {Difference of \var{t2} and \var{t3}.
+           Afterwards \var{t1} == \var{t2} - \var{t3} and
+           \var{t2} == \var{t1} + \var{t3} are true.
+          (1)}
+  \lineii{\var{t1} = \var{t2} * \var{i} or \var{t1} = \var{i} * \var{t2}}
+          {Delta multiplied by an integer or long.
+           Afterwards \var{t1} // i == \var{t2} is true,
+           provided \code{i != 0}.}
+  \lineii{}{In general, \var{t1} * i == \var{t1} * (i-1) + \var{t1} is true.
+          (1)}
+  \lineii{\var{t1} = \var{t2} // \var{i}}
+          {The floor is computed and the remainder (if any) is thrown away.
+          (3)}
+  \lineii{+\var{t1}}
+          {Returns a \class{timedelta} object with the same value.
+          (2)}
+  \lineii{-\var{t1}}
+          {equivalent to \class{timedelta}(-\var{t1.days}, -\var{t1.seconds},
+           -\var{t1.microseconds}), and to \var{t1}* -1.
+          (1)(4)}
+  \lineii{abs(\var{t})}
+          {equivalent to +\var{t} when \code{t.days >= 0}, and to
+           -\var{t} when \code{t.days < 0}.
+          (2)}
+\end{tableii}
+\noindent
+Notes:
+
+\begin{description}
+\item[(1)]
+  This is exact, but may overflow.
+
+\item[(2)]
+  This is exact, and cannot overflow.
+
+\item[(3)]
+  Division by 0 raises \exception{ZeroDivisionError}.
+
+\item[(4)]
+  -\var{timedelta.max} is not representable as a \class{timedelta} object.
+\end{description}
+
+In addition to the operations listed above \class{timedelta} objects
+support certain additions and subtractions with \class{date} and
+\class{datetime} objects (see below).
+
+Comparisons of \class{timedelta} objects are supported with the
+\class{timedelta} object representing the smaller duration considered
+to be the smaller timedelta.
+In order to stop mixed-type comparisons from falling back to the
+default comparison by object address, when a \class{timedelta} object is
+compared to an object of a different type, \exception{TypeError} is
+raised unless the comparison is \code{==} or \code{!=}.  The latter
+cases return \constant{False} or \constant{True}, respectively.
+
+\class{timedelta} objects are hashable (usable as dictionary keys),
+support efficient pickling, and in Boolean contexts, a \class{timedelta}
+object is considered to be true if and only if it isn't equal to
+\code{timedelta(0)}.
+
+
+\subsection{\class{date} Objects \label{datetime-date}}
+
+A \class{date} object represents a date (year, month and day) in an idealized
+calendar, the current Gregorian calendar indefinitely extended in both
+directions.  January 1 of year 1 is called day number 1, January 2 of year
+1 is called day number 2, and so on.  This matches the definition of the
+"proleptic Gregorian" calendar in Dershowitz and Reingold's book
+\citetitle{Calendrical Calculations}, where it's the base calendar for all
+computations.  See the book for algorithms for converting between
+proleptic Gregorian ordinals and many other calendar systems.
+
+\begin{classdesc}{date}{year, month, day}
+  All arguments are required.  Arguments may be ints or longs, in the
+  following ranges:
+
+  \begin{itemize}
+    \item \code{MINYEAR <= \var{year} <= MAXYEAR}
+    \item \code{1 <= \var{month} <= 12}
+    \item \code{1 <= \var{day} <= number of days in the given month and year}
+  \end{itemize}
+
+  If an argument outside those ranges is given, \exception{ValueError}
+  is raised.
+\end{classdesc}
+
+Other constructors, all class methods:
+
+\begin{methoddesc}{today}{}
+  Return the current local date.  This is equivalent to
+  \code{date.fromtimestamp(time.time())}.
+\end{methoddesc}
+
+\begin{methoddesc}{fromtimestamp}{timestamp}
+  Return the local date corresponding to the POSIX timestamp, such
+  as is returned by \function{time.time()}.  This may raise
+  \exception{ValueError}, if the timestamp is out of the range of
+  values supported by the platform C \cfunction{localtime()}
+  function.  It's common for this to be restricted to years from 1970
+  through 2038.  Note that on non-POSIX systems that include leap
+  seconds in their notion of a timestamp, leap seconds are ignored by
+  \method{fromtimestamp()}.
+\end{methoddesc}
+
+\begin{methoddesc}{fromordinal}{ordinal}
+  Return the date corresponding to the proleptic Gregorian ordinal,
+  where January 1 of year 1 has ordinal 1.  \exception{ValueError} is
+  raised unless \code{1 <= \var{ordinal} <= date.max.toordinal()}.
+  For any date \var{d}, \code{date.fromordinal(\var{d}.toordinal()) ==
+  \var{d}}.
+\end{methoddesc}
+
+Class attributes:
+
+\begin{memberdesc}{min}
+  The earliest representable date, \code{date(MINYEAR, 1, 1)}.
+\end{memberdesc}
+
+\begin{memberdesc}{max}
+  The latest representable date, \code{date(MAXYEAR, 12, 31)}.
+\end{memberdesc}
+
+\begin{memberdesc}{resolution}
+  The smallest possible difference between non-equal date
+  objects, \code{timedelta(days=1)}.
+\end{memberdesc}
+
+Instance attributes (read-only):
+
+\begin{memberdesc}{year}
+  Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive.
+\end{memberdesc}
+
+\begin{memberdesc}{month}
+  Between 1 and 12 inclusive.
+\end{memberdesc}
+
+\begin{memberdesc}{day}
+  Between 1 and the number of days in the given month of the given
+  year.
+\end{memberdesc}
+
+Supported operations:
+
+\begin{tableii}{c|l}{code}{Operation}{Result}
+  \lineii{\var{date2} = \var{date1} + \var{timedelta}}
+    {\var{date2} is \code{\var{timedelta}.days} days removed from
+    \var{date1}.  (1)}
+
+
+  \lineii{\var{date2} = \var{date1} - \var{timedelta}}
+   {Computes \var{date2} such that \code{\var{date2} + \var{timedelta}
+   == \var{date1}}. (2)}
+
+  \lineii{\var{timedelta} = \var{date1} - \var{date2}}
+   {(3)}
+
+  \lineii{\var{date1} < \var{date2}}
+   {\var{date1} is considered less than \var{date2} when \var{date1}
+   precedes \var{date2} in time. (4)}
+
+\end{tableii}
+
+Notes:
+\begin{description}
+
+\item[(1)]
+ \var{date2} is moved forward in time if \code{\var{timedelta}.days
+    > 0}, or backward if \code{\var{timedelta}.days < 0}.  Afterward
+    \code{\var{date2} - \var{date1} == \var{timedelta}.days}.
+    \code{\var{timedelta}.seconds} and
+    \code{\var{timedelta}.microseconds} are ignored.
+    \exception{OverflowError} is raised if \code{\var{date2}.year}
+    would be smaller than \constant{MINYEAR} or larger than
+    \constant{MAXYEAR}.
+
+\item[(2)]
+ This isn't quite equivalent to date1 +
+   (-timedelta), because -timedelta in isolation can overflow in cases
+   where date1 - timedelta does not.  \code{\var{timedelta}.seconds}
+   and \code{\var{timedelta}.microseconds} are ignored.
+
+\item[(3)]
+This is exact, and cannot overflow.  timedelta.seconds and
+    timedelta.microseconds are 0, and date2 + timedelta == date1
+    after.
+
+\item[(4)]
+In other words, \code{date1 < date2}
+   if and only if \code{\var{date1}.toordinal() <
+   \var{date2}.toordinal()}.
+In order to stop comparison from falling back to the default
+scheme of comparing object addresses, date comparison
+normally raises \exception{TypeError} if the other comparand
+isn't also a \class{date} object.  However, \code{NotImplemented}
+is returned instead if the other comparand has a
+\method{timetuple} attribute.  This hook gives other kinds of
+date objects a chance at implementing mixed-type comparison.
+If not, when a \class{date} object is
+compared to an object of a different type, \exception{TypeError} is
+raised unless the comparison is \code{==} or \code{!=}.  The latter
+cases return \constant{False} or \constant{True}, respectively.
+
+\end{description}
+
+
+Dates can be used as dictionary keys. In Boolean contexts, all
+\class{date} objects are considered to be true.
+
+Instance methods:
+
+\begin{methoddesc}{replace}{year, month, day}
+  Return a date with the same value, except for those members given
+  new values by whichever keyword arguments are specified.  For
+  example, if \code{d == date(2002, 12, 31)}, then
+  \code{d.replace(day=26) == date(2002, 12, 26)}.
+\end{methoddesc}
+
+\begin{methoddesc}{timetuple}{}
+  Return a \class{time.struct_time} such as returned by
+  \function{time.localtime()}.  The hours, minutes and seconds are
+  0, and the DST flag is -1.
+  \code{\var{d}.timetuple()} is equivalent to
+      \code{time.struct_time((\var{d}.year, \var{d}.month, \var{d}.day,
+             0, 0, 0,
+             \var{d}.weekday(),
+             \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
+            -1))}
+\end{methoddesc}
+
+\begin{methoddesc}{toordinal}{}
+  Return the proleptic Gregorian ordinal of the date, where January 1
+  of year 1 has ordinal 1.  For any \class{date} object \var{d},
+  \code{date.fromordinal(\var{d}.toordinal()) == \var{d}}.
+\end{methoddesc}
+
+\begin{methoddesc}{weekday}{}
+  Return the day of the week as an integer, where Monday is 0 and
+  Sunday is 6.  For example, \code{date(2002, 12, 4).weekday() == 2}, a
+  Wednesday.
+  See also \method{isoweekday()}.
+\end{methoddesc}
+
+\begin{methoddesc}{isoweekday}{}
+  Return the day of the week as an integer, where Monday is 1 and
+  Sunday is 7.  For example, \code{date(2002, 12, 4).isoweekday() == 3}, a
+  Wednesday.
+  See also \method{weekday()}, \method{isocalendar()}.
+\end{methoddesc}
+
+\begin{methoddesc}{isocalendar}{}
+  Return a 3-tuple, (ISO year, ISO week number, ISO weekday).
+
+  The ISO calendar is a widely used variant of the Gregorian calendar.
+  See \url{http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm}
+  for a good explanation.
+
+  The ISO year consists of 52 or 53 full weeks, and where a week starts
+  on a Monday and ends on a Sunday.  The first week of an ISO year is
+  the first (Gregorian) calendar week of a year containing a Thursday.
+  This is called week number 1, and the ISO year of that Thursday is
+  the same as its Gregorian year.
+
+  For example, 2004 begins on a Thursday, so the first week of ISO
+  year 2004 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan
+  2004, so that
+  \code{date(2003, 12, 29).isocalendar() == (2004, 1, 1)}
+  and
+  \code{date(2004, 1, 4).isocalendar() == (2004, 1, 7)}.
+\end{methoddesc}
+
+\begin{methoddesc}{isoformat}{}
+  Return a string representing the date in ISO 8601 format,
+  'YYYY-MM-DD'.  For example,
+  \code{date(2002, 12, 4).isoformat() == '2002-12-04'}.
+\end{methoddesc}
+
+\begin{methoddesc}{__str__}{}
+  For a date \var{d}, \code{str(\var{d})} is equivalent to
+  \code{\var{d}.isoformat()}.
+\end{methoddesc}
+
+\begin{methoddesc}{ctime}{}
+  Return a string representing the date, for example
+  date(2002, 12, 4).ctime() == 'Wed Dec  4 00:00:00 2002'.
+  \code{\var{d}.ctime()} is equivalent to
+  \code{time.ctime(time.mktime(\var{d}.timetuple()))}
+  on platforms where the native C \cfunction{ctime()} function
+  (which \function{time.ctime()} invokes, but which
+  \method{date.ctime()} does not invoke) conforms to the C standard.
+\end{methoddesc}
+
+\begin{methoddesc}{strftime}{format}
+  Return a string representing the date, controlled by an explicit
+  format string.  Format codes referring to hours, minutes or seconds
+  will see 0 values.
+  See section~\ref{strftime-behavior} -- \method{strftime()} behavior.
+\end{methoddesc}
+
+
+\subsection{\class{datetime} Objects \label{datetime-datetime}}
+
+A \class{datetime} object is a single object containing all the
+information from a \class{date} object and a \class{time} object.  Like a
+\class{date} object, \class{datetime} assumes the current Gregorian
+calendar extended in both directions; like a time object,
+\class{datetime} assumes there are exactly 3600*24 seconds in every
+day.
+
+Constructor:
+
+\begin{classdesc}{datetime}{year, month, day\optional{,
+                            hour\optional{, minute\optional{,
+                            second\optional{, microsecond\optional{,
+                            tzinfo}}}}}}
+  The year, month and day arguments are required.  \var{tzinfo} may
+  be \code{None}, or an instance of a \class{tzinfo} subclass.  The
+  remaining arguments may be ints or longs, in the following ranges:
+
+  \begin{itemize}
+    \item \code{MINYEAR <= \var{year} <= MAXYEAR}
+    \item \code{1 <= \var{month} <= 12}
+    \item \code{1 <= \var{day} <= number of days in the given month and year}
+    \item \code{0 <= \var{hour} < 24}
+    \item \code{0 <= \var{minute} < 60}
+    \item \code{0 <= \var{second} < 60}
+    \item \code{0 <= \var{microsecond} < 1000000}
+  \end{itemize}
+
+  If an argument outside those ranges is given,
+  \exception{ValueError} is raised.
+\end{classdesc}
+
+Other constructors, all class methods:
+
+\begin{methoddesc}{today}{}
+  Return the current local datetime, with \member{tzinfo} \code{None}.
+  This is equivalent to
+  \code{datetime.fromtimestamp(time.time())}.
+  See also \method{now()}, \method{fromtimestamp()}.
+\end{methoddesc}
+
+\begin{methoddesc}{now}{\optional{tz}}
+  Return the current local date and time.  If optional argument
+  \var{tz} is \code{None} or not specified, this is like
+  \method{today()}, but, if possible, supplies more precision than can
+  be gotten from going through a \function{time.time()} timestamp (for
+  example, this may be possible on platforms supplying the C
+  \cfunction{gettimeofday()} function).
+
+  Else \var{tz} must be an instance of a class \class{tzinfo} subclass,
+  and the current date and time are converted to \var{tz}'s time
+  zone.  In this case the result is equivalent to
+  \code{\var{tz}.fromutc(datetime.utcnow().replace(tzinfo=\var{tz}))}.
+  See also \method{today()}, \method{utcnow()}.
+\end{methoddesc}
+
+\begin{methoddesc}{utcnow}{}
+  Return the current UTC date and time, with \member{tzinfo} \code{None}.
+  This is like \method{now()}, but returns the current UTC date and time,
+  as a naive \class{datetime} object.
+  See also \method{now()}.
+\end{methoddesc}
+
+\begin{methoddesc}{fromtimestamp}{timestamp\optional{, tz}}
+  Return the local date and time corresponding to the \POSIX{}
+  timestamp, such as is returned by \function{time.time()}.
+  If optional argument \var{tz} is \code{None} or not specified, the
+  timestamp is converted to the platform's local date and time, and
+  the returned \class{datetime} object is naive.
+
+  Else \var{tz} must be an instance of a class \class{tzinfo} subclass,
+  and the timestamp is converted to \var{tz}'s time zone.  In this case
+  the result is equivalent to
+  \code{\var{tz}.fromutc(datetime.utcfromtimestamp(\var{timestamp}).replace(tzinfo=\var{tz}))}.
+
+  \method{fromtimestamp()} may raise \exception{ValueError}, if the
+  timestamp is out of the range of values supported by the platform C
+  \cfunction{localtime()} or \cfunction{gmtime()} functions.  It's common
+  for this to be restricted to years in 1970 through 2038.
+  Note that on non-POSIX systems that include leap seconds in their
+  notion of a timestamp, leap seconds are ignored by
+  \method{fromtimestamp()}, and then it's possible to have two timestamps
+  differing by a second that yield identical \class{datetime} objects.
+  See also \method{utcfromtimestamp()}.
+\end{methoddesc}
+
+\begin{methoddesc}{utcfromtimestamp}{timestamp}
+  Return the UTC \class{datetime} corresponding to the \POSIX{}
+  timestamp, with \member{tzinfo} \code{None}.
+  This may raise \exception{ValueError}, if the
+  timestamp is out of the range of values supported by the platform
+  C \cfunction{gmtime()} function.  It's common for this to be
+  restricted to years in 1970 through 2038.
+  See also \method{fromtimestamp()}.
+\end{methoddesc}
+
+\begin{methoddesc}{fromordinal}{ordinal}
+  Return the \class{datetime} corresponding to the proleptic
+  Gregorian ordinal, where January 1 of year 1 has ordinal 1.
+  \exception{ValueError} is raised unless \code{1 <= ordinal <=
+  datetime.max.toordinal()}.  The hour, minute, second and
+  microsecond of the result are all 0,
+  and \member{tzinfo} is \code{None}.
+\end{methoddesc}
+
+\begin{methoddesc}{combine}{date, time}
+  Return a new \class{datetime} object whose date members are
+  equal to the given \class{date} object's, and whose time
+  and \member{tzinfo} members are equal to the given \class{time} object's.
+  For any \class{datetime} object \var{d}, \code{\var{d} ==
+  datetime.combine(\var{d}.date(), \var{d}.timetz())}.  If date is a
+  \class{datetime} object, its time and \member{tzinfo} members are
+  ignored.
+  \end{methoddesc}
+
+\begin{methoddesc}{strptime}{date_string, format}
+  Return a \class{datetime} corresponding to \var{date_string}, parsed
+  according to \var{format}.  This is equivalent to
+  \code{datetime(*(time.strptime(date_string,
+  format)[0:6]))}. \exception{ValueError} is raised if the date_string and
+  format can't be parsed by \function{time.strptime()} or if it returns a
+  value which isn't a time tuple.
+
+  \versionadded{2.5}
+\end{methoddesc}
+
+Class attributes:
+
+\begin{memberdesc}{min}
+  The earliest representable \class{datetime},
+  \code{datetime(MINYEAR, 1, 1, tzinfo=None)}.
+\end{memberdesc}
+
+\begin{memberdesc}{max}
+  The latest representable \class{datetime},
+  \code{datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)}.
+\end{memberdesc}
+
+\begin{memberdesc}{resolution}
+  The smallest possible difference between non-equal \class{datetime}
+  objects, \code{timedelta(microseconds=1)}.
+\end{memberdesc}
+
+Instance attributes (read-only):
+
+\begin{memberdesc}{year}
+  Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive.
+\end{memberdesc}
+
+\begin{memberdesc}{month}
+  Between 1 and 12 inclusive.
+\end{memberdesc}
+
+\begin{memberdesc}{day}
+  Between 1 and the number of days in the given month of the given
+  year.
+\end{memberdesc}
+
+\begin{memberdesc}{hour}
+  In \code{range(24)}.
+\end{memberdesc}
+
+\begin{memberdesc}{minute}
+  In \code{range(60)}.
+\end{memberdesc}
+
+\begin{memberdesc}{second}
+  In \code{range(60)}.
+\end{memberdesc}
+
+\begin{memberdesc}{microsecond}
+  In \code{range(1000000)}.
+\end{memberdesc}
+
+\begin{memberdesc}{tzinfo}
+  The object passed as the \var{tzinfo} argument to the
+  \class{datetime} constructor, or \code{None} if none was passed.
+\end{memberdesc}
+
+Supported operations:
+
+\begin{tableii}{c|l}{code}{Operation}{Result}
+  \lineii{\var{datetime2} = \var{datetime1} + \var{timedelta}}{(1)}
+
+  \lineii{\var{datetime2} = \var{datetime1} - \var{timedelta}}{(2)}
+
+  \lineii{\var{timedelta} = \var{datetime1} - \var{datetime2}}{(3)}
+
+  \lineii{\var{datetime1} < \var{datetime2}}
+   {Compares \class{datetime} to \class{datetime}.
+    (4)}
+
+\end{tableii}
+
+\begin{description}
+
+\item[(1)]
+
+    datetime2 is a duration of timedelta removed from datetime1, moving
+    forward in time if \code{\var{timedelta}.days} > 0, or backward if
+    \code{\var{timedelta}.days} < 0.  The result has the same \member{tzinfo} member
+    as the input datetime, and datetime2 - datetime1 == timedelta after.
+    \exception{OverflowError} is raised if datetime2.year would be
+    smaller than \constant{MINYEAR} or larger than \constant{MAXYEAR}.
+    Note that no time zone adjustments are done even if the input is an
+    aware object.
+
+\item[(2)]
+    Computes the datetime2 such that datetime2 + timedelta == datetime1.
+    As for addition, the result has the same \member{tzinfo} member
+    as the input datetime, and no time zone adjustments are done even
+    if the input is aware.
+    This isn't quite equivalent to datetime1 + (-timedelta), because
+    -timedelta in isolation can overflow in cases where
+    datetime1 - timedelta does not.
+
+\item[(3)]
+    Subtraction of a \class{datetime} from a
+    \class{datetime} is defined only if both
+    operands are naive, or if both are aware.  If one is aware and the
+    other is naive, \exception{TypeError} is raised.
+
+    If both are naive, or both are aware and have the same \member{tzinfo}
+    member, the \member{tzinfo} members are ignored, and the result is
+    a \class{timedelta} object \var{t} such that
+    \code{\var{datetime2} + \var{t} == \var{datetime1}}.  No time zone
+    adjustments are done in this case.
+
+    If both are aware and have different \member{tzinfo} members,
+    \code{a-b} acts as if \var{a} and \var{b} were first converted to
+    naive UTC datetimes first.  The result is
+    \code{(\var{a}.replace(tzinfo=None) - \var{a}.utcoffset()) -
+          (\var{b}.replace(tzinfo=None) - \var{b}.utcoffset())}
+    except that the implementation never overflows.
+
+\item[(4)]
+
+\var{datetime1} is considered less than \var{datetime2}
+when \var{datetime1} precedes \var{datetime2} in time.
+
+If one comparand is naive and
+the other is aware, \exception{TypeError} is raised.  If both
+    comparands are aware, and have the same \member{tzinfo} member,
+    the common \member{tzinfo} member is ignored and the base datetimes
+    are compared.  If both comparands are aware and have different
+    \member{tzinfo} members, the comparands are first adjusted by
+    subtracting their UTC offsets (obtained from \code{self.utcoffset()}).
+    \note{In order to stop comparison from falling back to the default
+          scheme of comparing object addresses, datetime comparison
+          normally raises \exception{TypeError} if the other comparand
+          isn't also a \class{datetime} object.  However,
+          \code{NotImplemented} is returned instead if the other comparand
+          has a \method{timetuple} attribute.  This hook gives other
+          kinds of date objects a chance at implementing mixed-type
+          comparison.  If not, when a \class{datetime} object is
+          compared to an object of a different type, \exception{TypeError}
+          is raised unless the comparison is \code{==} or \code{!=}.  The
+          latter cases return \constant{False} or \constant{True},
+          respectively.}
+
+\end{description}
+
+\class{datetime} objects can be used as dictionary keys. In Boolean
+contexts, all \class{datetime} objects are considered to be true.
+
+
+Instance methods:
+
+\begin{methoddesc}{date}{}
+  Return \class{date} object with same year, month and day.
+\end{methoddesc}
+
+\begin{methoddesc}{time}{}
+  Return \class{time} object with same hour, minute, second and microsecond.
+  \member{tzinfo} is \code{None}.  See also method \method{timetz()}.
+\end{methoddesc}
+
+\begin{methoddesc}{timetz}{}
+  Return \class{time} object with same hour, minute, second, microsecond,
+  and tzinfo members.  See also method \method{time()}.
+\end{methoddesc}
+
+\begin{methoddesc}{replace}{\optional{year\optional{, month\optional{,
+                            day\optional{, hour\optional{, minute\optional{,
+                            second\optional{, microsecond\optional{,
+                            tzinfo}}}}}}}}}
+  Return a datetime with the same members, except for those members given
+  new values by whichever keyword arguments are specified.  Note that
+  \code{tzinfo=None} can be specified to create a naive datetime from
+  an aware datetime with no conversion of date and time members.
+\end{methoddesc}
+
+\begin{methoddesc}{astimezone}{tz}
+  Return a \class{datetime} object with new \member{tzinfo} member
+  \var{tz}, adjusting the date and time members so the result is the
+  same UTC time as \var{self}, but in \var{tz}'s local time.
+
+  \var{tz} must be an instance of a \class{tzinfo} subclass, and its
+  \method{utcoffset()} and \method{dst()} methods must not return
+  \code{None}.  \var{self} must be aware (\code{\var{self}.tzinfo} must
+  not be \code{None}, and \code{\var{self}.utcoffset()} must not return
+  \code{None}).
+
+  If \code{\var{self}.tzinfo} is \var{tz},
+  \code{\var{self}.astimezone(\var{tz})} is equal to \var{self}:  no
+  adjustment of date or time members is performed.
+  Else the result is local time in time zone \var{tz}, representing the
+  same UTC time as \var{self}:  after \code{\var{astz} =
+  \var{dt}.astimezone(\var{tz})},
+  \code{\var{astz} - \var{astz}.utcoffset()} will usually have the same
+  date and time members as \code{\var{dt} - \var{dt}.utcoffset()}.
+  The discussion of class \class{tzinfo} explains the cases at Daylight
+  Saving Time transition boundaries where this cannot be achieved (an issue
+  only if \var{tz} models both standard and daylight time).
+
+  If you merely want to attach a time zone object \var{tz} to a
+  datetime \var{dt} without adjustment of date and time members,
+  use \code{\var{dt}.replace(tzinfo=\var{tz})}.  If
+  you merely want to remove the time zone object from an aware datetime
+  \var{dt} without conversion of date and time members, use
+  \code{\var{dt}.replace(tzinfo=None)}.
+
+  Note that the default \method{tzinfo.fromutc()} method can be overridden
+  in a \class{tzinfo} subclass to affect the result returned by
+  \method{astimezone()}.  Ignoring error cases, \method{astimezone()}
+  acts like:
+
+  \begin{verbatim}
+  def astimezone(self, tz):
+      if self.tzinfo is tz:
+          return self
+      # Convert self to UTC, and attach the new time zone object.
+      utc = (self - self.utcoffset()).replace(tzinfo=tz)
+      # Convert from UTC to tz's local time.
+      return tz.fromutc(utc)
+  \end{verbatim}
+\end{methoddesc}
+
+\begin{methoddesc}{utcoffset}{}
+  If \member{tzinfo} is \code{None}, returns \code{None}, else
+  returns \code{\var{self}.tzinfo.utcoffset(\var{self})}, and
+  raises an exception if the latter doesn't return \code{None}, or
+  a \class{timedelta} object representing a whole number of minutes
+  with magnitude less than one day.
+\end{methoddesc}
+
+\begin{methoddesc}{dst}{}
+  If \member{tzinfo} is \code{None}, returns \code{None}, else
+  returns \code{\var{self}.tzinfo.dst(\var{self})}, and
+  raises an exception if the latter doesn't return \code{None}, or
+  a \class{timedelta} object representing a whole number of minutes
+  with magnitude less than one day.
+\end{methoddesc}
+
+\begin{methoddesc}{tzname}{}
+  If \member{tzinfo} is \code{None}, returns \code{None}, else
+  returns \code{\var{self}.tzinfo.tzname(\var{self})},
+  raises an exception if the latter doesn't return \code{None} or
+  a string object,
+\end{methoddesc}
+
+\begin{methoddesc}{timetuple}{}
+  Return a \class{time.struct_time} such as returned by
+  \function{time.localtime()}.
+  \code{\var{d}.timetuple()} is equivalent to
+  \code{time.struct_time((\var{d}.year, \var{d}.month, \var{d}.day,
+         \var{d}.hour, \var{d}.minute, \var{d}.second,
+         \var{d}.weekday(),
+         \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
+         dst))}
+  The \member{tm_isdst} flag of the result is set according to
+  the \method{dst()} method:  \member{tzinfo} is \code{None} or
+  \method{dst()} returns \code{None},
+  \member{tm_isdst} is set to  \code{-1}; else if \method{dst()} returns
+  a non-zero value, \member{tm_isdst} is set to \code{1};
+  else \code{tm_isdst} is set to \code{0}.
+\end{methoddesc}
+
+\begin{methoddesc}{utctimetuple}{}
+  If \class{datetime} instance \var{d} is naive, this is the same as
+  \code{\var{d}.timetuple()} except that \member{tm_isdst} is forced to 0
+  regardless of what \code{d.dst()} returns.  DST is never in effect
+  for a UTC time.
+
+  If \var{d} is aware, \var{d} is normalized to UTC time, by subtracting
+  \code{\var{d}.utcoffset()}, and a \class{time.struct_time} for the
+  normalized time is returned.  \member{tm_isdst} is forced to 0.
+  Note that the result's \member{tm_year} member may be
+  \constant{MINYEAR}-1 or \constant{MAXYEAR}+1, if \var{d}.year was
+  \code{MINYEAR} or \code{MAXYEAR} and UTC adjustment spills over a
+  year boundary.
+\end{methoddesc}
+
+\begin{methoddesc}{toordinal}{}
+  Return the proleptic Gregorian ordinal of the date.  The same as
+  \code{self.date().toordinal()}.
+\end{methoddesc}
+
+\begin{methoddesc}{weekday}{}
+  Return the day of the week as an integer, where Monday is 0 and
+  Sunday is 6.  The same as \code{self.date().weekday()}.
+  See also \method{isoweekday()}.
+\end{methoddesc}
+
+\begin{methoddesc}{isoweekday}{}
+  Return the day of the week as an integer, where Monday is 1 and
+  Sunday is 7.  The same as \code{self.date().isoweekday()}.
+  See also \method{weekday()}, \method{isocalendar()}.
+\end{methoddesc}
+
+\begin{methoddesc}{isocalendar}{}
+  Return a 3-tuple, (ISO year, ISO week number, ISO weekday).  The
+  same as \code{self.date().isocalendar()}.
+\end{methoddesc}
+
+\begin{methoddesc}{isoformat}{\optional{sep}}
+  Return a string representing the date and time in ISO 8601 format,
+      YYYY-MM-DDTHH:MM:SS.mmmmmm
+  or, if \member{microsecond} is 0,
+      YYYY-MM-DDTHH:MM:SS
+
+  If \method{utcoffset()} does not return \code{None}, a 6-character
+  string is appended, giving the UTC offset in (signed) hours and
+  minutes:
+      YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM
+  or, if \member{microsecond} is 0
+      YYYY-MM-DDTHH:MM:SS+HH:MM
+
+  The optional argument \var{sep} (default \code{'T'}) is a
+  one-character separator, placed between the date and time portions
+  of the result.  For example,
+
+\begin{verbatim}
+>>> from datetime import tzinfo, timedelta, datetime
+>>> class TZ(tzinfo):
+...     def utcoffset(self, dt): return timedelta(minutes=-399)
+...
+>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
+'2002-12-25 00:00:00-06:39'
+\end{verbatim}
+\end{methoddesc}
+
+\begin{methoddesc}{__str__}{}
+  For a \class{datetime} instance \var{d}, \code{str(\var{d})} is
+  equivalent to \code{\var{d}.isoformat(' ')}.
+\end{methoddesc}
+
+\begin{methoddesc}{ctime}{}
+  Return a string representing the date and time, for example
+  \code{datetime(2002, 12, 4, 20, 30, 40).ctime() ==
+   'Wed Dec  4 20:30:40 2002'}.
+  \code{d.ctime()} is equivalent to
+  \code{time.ctime(time.mktime(d.timetuple()))} on platforms where
+  the native C \cfunction{ctime()} function (which
+  \function{time.ctime()} invokes, but which
+  \method{datetime.ctime()} does not invoke) conforms to the C
+  standard.
+\end{methoddesc}
+
+\begin{methoddesc}{strftime}{format}
+  Return a string representing the date and time, controlled by an
+  explicit format string.  See section~\ref{strftime-behavior} --
+  \method{strftime()} behavior.
+\end{methoddesc}
+
+
+\subsection{\class{time} Objects \label{datetime-time}}
+
+A time object represents a (local) time of day, independent of any
+particular day, and subject to adjustment via a \class{tzinfo} object.
+
+\begin{classdesc}{time}{hour\optional{, minute\optional{, second\optional{,
+                        microsecond\optional{, tzinfo}}}}}
+  All arguments are optional.  \var{tzinfo} may be \code{None}, or
+  an instance of a \class{tzinfo} subclass.  The remaining arguments
+  may be ints or longs, in the following ranges:
+
+  \begin{itemize}
+    \item \code{0 <= \var{hour} < 24}
+    \item \code{0 <= \var{minute} < 60}
+    \item \code{0 <= \var{second} < 60}
+    \item \code{0 <= \var{microsecond} < 1000000}.
+  \end{itemize}
+
+  If an argument outside those ranges is given,
+  \exception{ValueError} is raised.  All default to \code{0} except
+  \var{tzinfo}, which defaults to \constant{None}.
+\end{classdesc}
+
+Class attributes:
+
+\begin{memberdesc}{min}
+  The earliest representable \class{time}, \code{time(0, 0, 0, 0)}.
+\end{memberdesc}
+
+\begin{memberdesc}{max}
+  The latest representable \class{time}, \code{time(23, 59, 59, 999999)}.
+\end{memberdesc}
+
+\begin{memberdesc}{resolution}
+  The smallest possible difference between non-equal \class{time}
+  objects, \code{timedelta(microseconds=1)}, although note that
+  arithmetic on \class{time} objects is not supported.
+\end{memberdesc}
+
+Instance attributes (read-only):
+
+\begin{memberdesc}{hour}
+  In \code{range(24)}.
+\end{memberdesc}
+
+\begin{memberdesc}{minute}
+  In \code{range(60)}.
+\end{memberdesc}
+
+\begin{memberdesc}{second}
+  In \code{range(60)}.
+\end{memberdesc}
+
+\begin{memberdesc}{microsecond}
+  In \code{range(1000000)}.
+\end{memberdesc}
+
+\begin{memberdesc}{tzinfo}
+  The object passed as the tzinfo argument to the \class{time}
+  constructor, or \code{None} if none was passed.
+\end{memberdesc}
+
+Supported operations:
+
+\begin{itemize}
+  \item
+    comparison of \class{time} to \class{time},
+    where \var{a} is considered less than \var{b} when \var{a} precedes
+    \var{b} in time.  If one comparand is naive and the other is aware,
+    \exception{TypeError} is raised.  If both comparands are aware, and
+    have the same \member{tzinfo} member, the common \member{tzinfo}
+    member is ignored and the base times are compared.  If both
+    comparands are aware and have different \member{tzinfo} members,
+    the comparands are first adjusted by subtracting their UTC offsets
+    (obtained from \code{self.utcoffset()}).
+    In order to stop mixed-type comparisons from falling back to the
+    default comparison by object address, when a \class{time} object is
+    compared to an object of a different type, \exception{TypeError} is
+    raised unless the comparison is \code{==} or \code{!=}.  The latter
+    cases return \constant{False} or \constant{True}, respectively.
+
+  \item
+    hash, use as dict key
+
+  \item
+    efficient pickling
+
+  \item
+    in Boolean contexts, a \class{time} object is considered to be
+    true if and only if, after converting it to minutes and
+    subtracting \method{utcoffset()} (or \code{0} if that's
+    \code{None}), the result is non-zero.
+\end{itemize}
+
+Instance methods:
+
+\begin{methoddesc}{replace}{\optional{hour\optional{, minute\optional{,
+                            second\optional{, microsecond\optional{,
+                            tzinfo}}}}}}
+  Return a \class{time} with the same value, except for those members given
+  new values by whichever keyword arguments are specified.  Note that
+  \code{tzinfo=None} can be specified to create a naive \class{time} from
+  an aware \class{time}, without conversion of the time members.
+\end{methoddesc}
+
+\begin{methoddesc}{isoformat}{}
+  Return a string representing the time in ISO 8601 format,
+      HH:MM:SS.mmmmmm
+  or, if self.microsecond is 0,
+      HH:MM:SS
+  If \method{utcoffset()} does not return \code{None}, a 6-character
+  string is appended, giving the UTC offset in (signed) hours and
+  minutes:
+      HH:MM:SS.mmmmmm+HH:MM
+  or, if self.microsecond is 0,
+      HH:MM:SS+HH:MM
+\end{methoddesc}
+
+\begin{methoddesc}{__str__}{}
+  For a time \var{t}, \code{str(\var{t})} is equivalent to
+  \code{\var{t}.isoformat()}.
+\end{methoddesc}
+
+\begin{methoddesc}{strftime}{format}
+  Return a string representing the time, controlled by an explicit
+  format string.  See section~\ref{strftime-behavior} --
+  \method{strftime()} behavior.
+\end{methoddesc}
+
+\begin{methoddesc}{utcoffset}{}
+  If \member{tzinfo} is \code{None}, returns \code{None}, else
+  returns \code{\var{self}.tzinfo.utcoffset(None)}, and
+  raises an exception if the latter doesn't return \code{None} or
+  a \class{timedelta} object representing a whole number of minutes
+  with magnitude less than one day.
+\end{methoddesc}
+
+\begin{methoddesc}{dst}{}
+  If \member{tzinfo} is \code{None}, returns \code{None}, else
+  returns \code{\var{self}.tzinfo.dst(None)}, and
+  raises an exception if the latter doesn't return \code{None}, or
+  a \class{timedelta} object representing a whole number of minutes
+  with magnitude less than one day.
+\end{methoddesc}
+
+\begin{methoddesc}{tzname}{}
+  If \member{tzinfo} is \code{None}, returns \code{None}, else
+  returns \code{\var{self}.tzinfo.tzname(None)}, or
+  raises an exception if the latter doesn't return \code{None} or
+  a string object.
+\end{methoddesc}
+
+
+\subsection{\class{tzinfo} Objects \label{datetime-tzinfo}}
+
+\class{tzinfo} is an abstract base clase, meaning that this class
+should not be instantiated directly.  You need to derive a concrete
+subclass, and (at least) supply implementations of the standard
+\class{tzinfo} methods needed by the \class{datetime} methods you
+use.  The \module{datetime} module does not supply any concrete
+subclasses of \class{tzinfo}.
+
+An instance of (a concrete subclass of) \class{tzinfo} can be passed
+to the constructors for \class{datetime} and \class{time} objects.
+The latter objects view their members as being in local time, and the
+\class{tzinfo} object supports methods revealing offset of local time
+from UTC, the name of the time zone, and DST offset, all relative to a
+date or time object passed to them.
+
+Special requirement for pickling:  A \class{tzinfo} subclass must have an
+\method{__init__} method that can be called with no arguments, else it
+can be pickled but possibly not unpickled again.  This is a technical
+requirement that may be relaxed in the future.
+
+A concrete subclass of \class{tzinfo} may need to implement the
+following methods.  Exactly which methods are needed depends on the
+uses made of aware \module{datetime} objects.  If in doubt, simply
+implement all of them.
+
+\begin{methoddesc}{utcoffset}{self, dt}
+  Return offset of local time from UTC, in minutes east of UTC.  If
+  local time is west of UTC, this should be negative.  Note that this
+  is intended to be the total offset from UTC; for example, if a
+  \class{tzinfo} object represents both time zone and DST adjustments,
+  \method{utcoffset()} should return their sum.  If the UTC offset
+  isn't known, return \code{None}.  Else the value returned must be
+  a \class{timedelta} object specifying a whole number of minutes in the
+  range -1439 to 1439 inclusive (1440 = 24*60; the magnitude of the offset
+  must be less than one day).  Most implementations of
+  \method{utcoffset()} will probably look like one of these two:
+
+\begin{verbatim}
+    return CONSTANT                 # fixed-offset class
+    return CONSTANT + self.dst(dt)  # daylight-aware class
+\end{verbatim}
+
+    If \method{utcoffset()} does not return \code{None},
+    \method{dst()} should not return \code{None} either.
+
+    The default implementation of \method{utcoffset()} raises
+    \exception{NotImplementedError}.
+\end{methoddesc}
+
+\begin{methoddesc}{dst}{self, dt}
+  Return the daylight saving time (DST) adjustment, in minutes east of
+  UTC, or \code{None} if DST information isn't known.  Return
+  \code{timedelta(0)} if DST is not in effect.
+  If DST is in effect, return the offset as a
+  \class{timedelta} object (see \method{utcoffset()} for details).
+  Note that DST offset, if applicable, has
+  already been added to the UTC offset returned by
+  \method{utcoffset()}, so there's no need to consult \method{dst()}
+  unless you're interested in obtaining DST info separately.  For
+  example, \method{datetime.timetuple()} calls its \member{tzinfo}
+  member's \method{dst()} method to determine how the
+  \member{tm_isdst} flag should be set, and
+  \method{tzinfo.fromutc()} calls \method{dst()} to account for
+  DST changes when crossing time zones.
+
+  An instance \var{tz} of a \class{tzinfo} subclass that models both
+  standard and daylight times must be consistent in this sense:
+
+      \code{\var{tz}.utcoffset(\var{dt}) - \var{tz}.dst(\var{dt})}
+
+  must return the same result for every \class{datetime} \var{dt}
+  with \code{\var{dt}.tzinfo == \var{tz}}  For sane \class{tzinfo}
+  subclasses, this expression yields the time zone's "standard offset",
+  which should not depend on the date or the time, but only on geographic
+  location.  The implementation of \method{datetime.astimezone()} relies
+  on this, but cannot detect violations; it's the programmer's
+  responsibility to ensure it.  If a \class{tzinfo} subclass cannot
+  guarantee this, it may be able to override the default implementation
+  of \method{tzinfo.fromutc()} to work correctly with \method{astimezone()}
+  regardless.
+
+  Most implementations of \method{dst()} will probably look like one
+  of these two:
+
+\begin{verbatim}
+    def dst(self):
+        # a fixed-offset class:  doesn't account for DST
+        return timedelta(0)
+\end{verbatim}
+
+  or
+
+\begin{verbatim}
+    def dst(self):
+        # Code to set dston and dstoff to the time zone's DST
+        # transition times based on the input dt.year, and expressed
+        # in standard local time.  Then
+
+        if dston <= dt.replace(tzinfo=None) < dstoff:
+            return timedelta(hours=1)
+        else:
+            return timedelta(0)
+\end{verbatim}
+
+  The default implementation of \method{dst()} raises
+  \exception{NotImplementedError}.
+\end{methoddesc}
+
+\begin{methoddesc}{tzname}{self, dt}
+  Return the time zone name corresponding to the \class{datetime}
+  object \var{dt}, as a string.
+  Nothing about string names is defined by the
+  \module{datetime} module, and there's no requirement that it mean
+  anything in particular.  For example, "GMT", "UTC", "-500", "-5:00",
+  "EDT", "US/Eastern", "America/New York" are all valid replies.  Return
+  \code{None} if a string name isn't known.  Note that this is a method
+  rather than a fixed string primarily because some \class{tzinfo}
+  subclasses will wish to return different names depending on the specific
+  value of \var{dt} passed, especially if the \class{tzinfo} class is
+  accounting for daylight time.
+
+  The default implementation of \method{tzname()} raises
+  \exception{NotImplementedError}.
+\end{methoddesc}
+
+These methods are called by a \class{datetime} or \class{time} object,
+in response to their methods of the same names.  A \class{datetime}
+object passes itself as the argument, and a \class{time} object passes
+\code{None} as the argument.  A \class{tzinfo} subclass's methods should
+therefore be prepared to accept a \var{dt} argument of \code{None}, or of
+class \class{datetime}.
+
+When \code{None} is passed, it's up to the class designer to decide the
+best response.  For example, returning \code{None} is appropriate if the
+class wishes to say that time objects don't participate in the
+\class{tzinfo} protocols.  It may be more useful for \code{utcoffset(None)}
+to return the standard UTC offset, as there is no other convention for
+discovering the standard offset.
+
+When a \class{datetime} object is passed in response to a
+\class{datetime} method, \code{dt.tzinfo} is the same object as
+\var{self}.  \class{tzinfo} methods can rely on this, unless
+user code calls \class{tzinfo} methods directly.  The intent is that
+the \class{tzinfo} methods interpret \var{dt} as being in local time,
+and not need worry about objects in other timezones.
+
+There is one more \class{tzinfo} method that a subclass may wish to
+override:
+
+\begin{methoddesc}{fromutc}{self, dt}
+  This is called from the default \class{datetime.astimezone()}
+  implementation.  When called from that, \code{\var{dt}.tzinfo} is
+  \var{self}, and \var{dt}'s date and time members are to be viewed as
+  expressing a UTC time.  The purpose of \method{fromutc()} is to
+  adjust the date and time members, returning an equivalent datetime in
+  \var{self}'s local time.
+
+  Most \class{tzinfo} subclasses should be able to inherit the default
+  \method{fromutc()} implementation without problems.  It's strong enough
+  to handle fixed-offset time zones, and time zones accounting for both
+  standard and daylight time, and the latter even if the DST transition
+  times differ in different years.  An example of a time zone the default
+  \method{fromutc()} implementation may not handle correctly in all cases
+  is one where the standard offset (from UTC) depends on the specific date
+  and time passed, which can happen for political reasons.
+  The default implementations of \method{astimezone()} and
+  \method{fromutc()} may not produce the result you want if the result is
+  one of the hours straddling the moment the standard offset changes.
+
+  Skipping code for error cases, the default \method{fromutc()}
+  implementation acts like:
+
+  \begin{verbatim}
+  def fromutc(self, dt):
+      # raise ValueError error if dt.tzinfo is not self
+      dtoff = dt.utcoffset()
+      dtdst = dt.dst()
+      # raise ValueError if dtoff is None or dtdst is None
+      delta = dtoff - dtdst  # this is self's standard offset
+      if delta:
+          dt += delta   # convert to standard local time
+          dtdst = dt.dst()
+          # raise ValueError if dtdst is None
+      if dtdst:
+          return dt + dtdst
+      else:
+          return dt
+  \end{verbatim}
+\end{methoddesc}
+
+Example \class{tzinfo} classes:
+
+\verbatiminput{tzinfo-examples.py}
+
+Note that there are unavoidable subtleties twice per year in a
+\class{tzinfo}
+subclass accounting for both standard and daylight time, at the DST
+transition points.  For concreteness, consider US Eastern (UTC -0500),
+where EDT begins the minute after 1:59 (EST) on the first Sunday in
+April, and ends the minute after 1:59 (EDT) on the last Sunday in October:
+
+\begin{verbatim}
+    UTC   3:MM  4:MM  5:MM  6:MM  7:MM  8:MM
+    EST  22:MM 23:MM  0:MM  1:MM  2:MM  3:MM
+    EDT  23:MM  0:MM  1:MM  2:MM  3:MM  4:MM
+
+  start  22:MM 23:MM  0:MM  1:MM  3:MM  4:MM
+
+    end  23:MM  0:MM  1:MM  1:MM  2:MM  3:MM
+\end{verbatim}
+
+When DST starts (the "start" line), the local wall clock leaps from 1:59
+to 3:00.  A wall time of the form 2:MM doesn't really make sense on that
+day, so \code{astimezone(Eastern)} won't deliver a result with
+\code{hour == 2} on the
+day DST begins.  In order for \method{astimezone()} to make this
+guarantee, the \method{rzinfo.dst()} method must consider times
+in the "missing hour" (2:MM for Eastern) to be in daylight time.
+
+When DST ends (the "end" line), there's a potentially worse problem:
+there's an hour that can't be spelled unambiguously in local wall time:
+the last hour of daylight time.  In Eastern, that's times of
+the form 5:MM UTC on the day daylight time ends.  The local wall clock
+leaps from 1:59 (daylight time) back to 1:00 (standard time) again.
+Local times of the form 1:MM are ambiguous.  \method{astimezone()} mimics
+the local clock's behavior by mapping two adjacent UTC hours into the
+same local hour then.  In the Eastern example, UTC times of the form
+5:MM and 6:MM both map to 1:MM when converted to Eastern.  In order for
+\method{astimezone()} to make this guarantee, the \method{tzinfo.dst()}
+method must consider times in the "repeated hour" to be in
+standard time.  This is easily arranged, as in the example, by expressing
+DST switch times in the time zone's standard local time.
+
+Applications that can't bear such ambiguities should avoid using hybrid
+\class{tzinfo} subclasses; there are no ambiguities when using UTC, or
+any other fixed-offset \class{tzinfo} subclass (such as a class
+representing only EST (fixed offset -5 hours), or only EDT (fixed offset
+-4 hours)).
+
+
+\subsection{\method{strftime()} Behavior\label{strftime-behavior}}
+
+\class{date}, \class{datetime}, and \class{time}
+objects all support a \code{strftime(\var{format})}
+method, to create a string representing the time under the control of
+an explicit format string.  Broadly speaking,
+\code{d.strftime(fmt)}
+acts like the \refmodule{time} module's
+\code{time.strftime(fmt, d.timetuple())}
+although not all objects support a \method{timetuple()} method.
+
+For \class{time} objects, the format codes for
+year, month, and day should not be used, as time objects have no such
+values.  If they're used anyway, \code{1900} is substituted for the
+year, and \code{0} for the month and day.
+
+For \class{date} objects, the format codes for hours, minutes, and
+seconds should not be used, as \class{date} objects have no such
+values.  If they're used anyway, \code{0} is substituted for them.
+
+For a naive object, the \code{\%z} and \code{\%Z} format codes are
+replaced by empty strings.
+
+For an aware object:
+
+\begin{itemize}
+  \item[\code{\%z}]
+    \method{utcoffset()} is transformed into a 5-character string of
+    the form +HHMM or -HHMM, where HH is a 2-digit string giving the
+    number of UTC offset hours, and MM is a 2-digit string giving the
+    number of UTC offset minutes.  For example, if
+    \method{utcoffset()} returns \code{timedelta(hours=-3, minutes=-30)},
+    \code{\%z} is replaced with the string \code{'-0330'}.
+
+  \item[\code{\%Z}]
+    If \method{tzname()} returns \code{None}, \code{\%Z} is replaced
+    by an empty string.  Otherwise \code{\%Z} is replaced by the returned
+    value, which must be a string.
+\end{itemize}
+
+The full set of format codes supported varies across platforms,
+because Python calls the platform C library's \function{strftime()}
+function, and platform variations are common.  The documentation for
+Python's \refmodule{time} module lists the format codes that the C
+standard (1989 version) requires, and those work on all platforms
+with a standard C implementation.  Note that the 1999 version of the
+C standard added additional format codes.
+
+The exact range of years for which \method{strftime()} works also
+varies across platforms.  Regardless of platform, years before 1900
+cannot be used.
+
+%%% This example is obsolete, since strptime is now supported by datetime.
+% 
+% \subsection{Examples}
+% 
+% \subsubsection{Creating Datetime Objects from Formatted Strings}
+% 
+% The \class{datetime} class does not directly support parsing formatted time
+% strings.  You can use \function{time.strptime} to do the parsing and create
+% a \class{datetime} object from the tuple it returns:
+% 
+% \begin{verbatim}
+% >>> s = "2005-12-06T12:13:14"
+% >>> from datetime import datetime
+% >>> from time import strptime
+% >>> datetime(*strptime(s, "%Y-%m-%dT%H:%M:%S")[0:6])
+% datetime.datetime(2005, 12, 6, 12, 13, 14)
+% \end{verbatim}
+%