diff options
Diffstat (limited to 'Doc/lib/libdatetime.tex')
| -rw-r--r-- | Doc/lib/libdatetime.tex | 1441 |
1 files changed, 0 insertions, 1441 deletions
diff --git a/Doc/lib/libdatetime.tex b/Doc/lib/libdatetime.tex deleted file mode 100644 index fb13ea7389..0000000000 --- a/Doc/lib/libdatetime.tex +++ /dev/null @@ -1,1441 +0,0 @@ -% 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}[tzinfo]{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}[tzinfo]{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}[tzinfo]{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}[tzinfo]{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} -% |