diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/lib/libdatetime.tex | 822 |
1 files changed, 266 insertions, 556 deletions
diff --git a/Doc/lib/libdatetime.tex b/Doc/lib/libdatetime.tex index 8878e3b..89e9406 100644 --- a/Doc/lib/libdatetime.tex +++ b/Doc/lib/libdatetime.tex @@ -16,22 +16,22 @@ 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 field extraction, for output formatting and manipulation. +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 savings time, or other kind of algorithmic or political -time adjustment. Whether a {naive} \class{datetime} object represents +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 meters, 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, ``aware'' \class{datetime} subclasses add an -optional time zone information object to the basic naive classes. +For applications requiring more, \class{datetime} and \class{time} objects +have an optional time zone information member. These \class{tzinfo} objects capture information about the offset from -UTC time, the time zone name, and whether Daylight Savings Time is in +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. Instead, they provide a framework for incorporating the level of detail an app may require. The rules for @@ -41,14 +41,14 @@ there is no standard suitable for every app. The \module{datetime} module exports the following constants: \begin{datadesc}{MINYEAR} - The smallest year number allowed in a \class{date}, - \class{datetime}, or \class{datetimetz} object. \constant{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}, \class{datetime}, - or \class{datetimetz} object. \constant{MAXYEAR} is \code{9999}. + The largest year number allowed in a \class{date} or \class{datetime} + object. \constant{MAXYEAR} is \code{9999}. \end{datadesc} \begin{seealso} @@ -65,18 +65,18 @@ The \module{datetime} module exports the following constants: \end{classdesc*} \begin{classdesc*}{time} - An idealized naive time, independent of any particular day, assuming + 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}, and - \member{microsecond} + Attributes: \member{hour}, \member{minute}, \member{second}, + \member{microsecond}, and \member{tzinfo}. \end{classdesc*} \begin{classdesc*}{datetime} - A combination of a naive date and a naive time. + A combination of a naive date and a time. Attributes: \member{year}, \member{month}, \member{day}, \member{hour}, \member{minute}, \member{second}, - and \member{microsecond}. + \member{microsecond}, and \member{tzinfo}. \end{classdesc*} \begin{classdesc*}{timedelta} @@ -87,27 +87,16 @@ The \module{datetime} module exports the following constants: \begin{classdesc*}{tzinfo} An abstract base class for time zone information objects. These - are used by the \class{datetimetz} and \class{timetz} classes to + are used by the \class{datetime} and \class{time} classes to provided a customizable notion of time adjustment (for example, to - account for time zone and/or daylight savings time). -\end{classdesc*} - -\begin{classdesc*}{timetz} - An aware subclass of \class{time}, supporting a customizable notion of - time adjustment. -\end{classdesc*} - -\begin{classdesc*}{datetimetz} - An aware subclass of \class{datetime}, supporting a customizable notion of - time adjustment. + account for time zone and/or daylight saving time). \end{classdesc*} Objects of these types are immutable. -Objects of the \class{date}, \class{datetime}, and \class{time} types -are always naive. +Objects of the \class{date} type are always naive. -An object \var{d} of type \class{timetz} or \class{datetimetz} may be +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 @@ -125,10 +114,8 @@ object timedelta tzinfo time - timetz date datetime - datetimetz \end{verbatim} \subsection{\class{timedelta} Objects \label{datetime-timedelta}} @@ -263,8 +250,8 @@ Notes: \end{description} In addition to the operations listed above \class{timedelta} objects -support certain additions and subtractions with \class{date}, -\class{datetime}, and \class{datimetz} objects (see below). +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 @@ -361,7 +348,9 @@ Supported operations: \begin{itemize} \item date1 + timedelta -> date2 + timedelta + date1 -> date2 + date2 is timedelta.days days removed from the date1, moving forward in time if timedelta.days > 0, or backward if timedetla.days < 0. date2 - date1 == timedelta.days after. timedelta.seconds and @@ -371,6 +360,7 @@ Supported operations: \item date1 - timedelta -> date2 + Computes the date2 such that date2 + timedelta == date1. This isn't quite equivalent to date1 + (-timedelta), because -timedelta in isolation can overflow in cases where date1 - timedelta does @@ -378,6 +368,7 @@ Supported operations: \item date1 - date2 -> timedelta + This is exact, and cannot overflow. timedelta.seconds and timedelta.microseconds are 0, and date2 + timedelta == date1 after. @@ -400,7 +391,7 @@ Supported operations: Instance methods: \begin{methoddesc}{replace}{year, month, day} - Return a date with the same value, except for those fields given + 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(2000, 12, 26)}. @@ -492,19 +483,23 @@ Instance methods: \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 time object. Like a +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, - hour=0, minute=0, second=0, microsecond=0} - The year, month and day arguments are required. Arguments may be - ints or longs, in the following ranges: + hour=0, minute=0, second=0, microsecond=0, + tzinfo=None} + 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{\member{MINYEAR} <= \var{year} <= \member{MAXYEAR}} + \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} @@ -513,14 +508,15 @@ day. \item \code{0 <= \var{microsecond} < 1000000} \end{itemize} - If an argument outside those ranges is given, \exception{ValueError} - is raised. + 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. This is equivalent to + 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} @@ -535,7 +531,8 @@ Other constructors, all class methods: \end{methoddesc} \begin{methoddesc}{utcnow}{} - Return the current UTC datetime. This is like \method{now()}, but + Return the current UTC datetime, with \member{tzinfo} \code{None}. + This is like \method{now()}, but returns the current UTC date and time. See also \method{now()}. \end{methoddesc} @@ -551,13 +548,13 @@ Other constructors, all class methods: 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. -\end{methoddesc} See also \method{utcfromtimestamp()}. \end{methoddesc} \begin{methoddesc}{utcfromtimestamp}{timestamp} Return the UTC \class{datetime} corresponding to the \POSIX{} - timestamp. This may raise \exception{ValueError}, if the + 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. @@ -569,31 +566,30 @@ Other constructors, all class methods: Gregorian ordinal, where January 1 of year 1 has ordinal 1. \exception{ValueError} is raised unless 1 <= ordinal <= datetime.max.toordinal(). The hour, minute, second and - microsecond of the result are all 0. + 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 components are + Return a new \class{datetime} object whose date members are equal to the given \class{date} object's, and whose time - components are equal to the given time object's. For any - \class{datetime} object \var{d}, \code{\var{d} == - datetime.combine(\var{d}.date(), \var{d}.time())}. If date is a - \class{datetime} or \class{datetimetz} object, its time components - are ignored. If date is \class{datetimetz} object, its - \member{tzinfo} component is also ignored. If time is a - \class{timetz} object, its \member{tzinfo} component is ignored. -\end{methoddesc} + 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} Class attributes: \begin{memberdesc}{min} The earliest representable \class{datetime}, - \code{datetime(MINYEAR, 1, 1)}. + \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)}. + \code{datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)}. \end{memberdesc} \begin{memberdesc}{resolution} @@ -604,11 +600,11 @@ Class attributes: Instance attributes (read-only): \begin{memberdesc}{year} - Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive + Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive. \end{memberdesc} \begin{memberdesc}{month} - Between 1 and 12 inclusive + Between 1 and 12 inclusive. \end{memberdesc} \begin{memberdesc}{day} @@ -632,34 +628,70 @@ Instance attributes (read-only): 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{itemize} \item datetime1 + timedelta -> datetime2 + timedelta + datetime1 -> datetime2 + datetime2 is a duration of timedelta removed from datetime1, moving forward in time if timedelta.days > 0, or backward if - timedelta.days < 0. datetime2 - datetime1 == timedelta after. + 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 datetime1 - timedelta -> datetime2 + 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 datetime1 - datetime2 -> timedelta - This is exact, and cannot overflow. - datetime2 + timedelta == datetime1 after. + + 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 - comparison of \class{datetime} to datetime, where datetime1 is - considered less than datetime2 when datetime1 precedes datetime2 - in time. + comparison of \class{datetime} to \class{datetime}, + 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 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()}). \item hash, use as dict key @@ -679,65 +711,132 @@ Instance methods: \end{methoddesc} \begin{methoddesc}{time}{} - Return time object with same hour, minute, second and microsecond. + 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}{replace}{year=, month=, day=, hour=, minute=, - second=, microsecond=} - Return a datetime with the same value, except for those fields given - new values by whichever keyword arguments are specified. +\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}{year=, month=, day=, hour=, minute=, second=, + microsecond=, 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{datetimetz} with the same date and time fields, and - with \member{tzinfo} member \var{tz}. \var{tz} must be \code{None}, - or an instance of a \class{tzinfo} subclass. + Return a \class{datetime} object with new \member{tzinfo} member + \var{tz}. + \var{tz} must be \code{None}, or an instance of a \class{tzinfo} subclass. + If \var{tz} is \code{None}, \var{self} is naive, + or \code{self.tzinfo}\ is \var{tz}, + \code{self.astimezone(tz)} is equivalent to + \code{self.replace(tzinfo=tz)}: a new time zone object is attached + without any conversion of date or time members. Else \code{self.tzinfo} + and \var{tz} must implement the \method{utcoffset()} and \method{dst()} + \class{tzinfo} methods, and the date and time members are adjusted so + that the result is local time in time zone \var{tz}, representing the + same UTC time as \var{self}: after \code{astz = dt.astimezone(tz)}, + \code{astz - astz.utcoffset()} will usually have the same date and time + members as \code{dt - 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). +\end{methoddesc} + +\begin{methoddesc}{utcoffset}{} + If \member{tzinfo} is \code{None}, returns \code{None}, else + returns \code{tzinfo.utcoffset(self)}. +\end{methoddesc} + +\begin{methoddesc}{tzname}{} + If \member{tzinfo} is \code{None}, returns \code{None}, else + returns \code{tzinfo.tzname(self)}. \end{methoddesc} \begin{methoddesc}{timetuple}{} Return a 9-element tuple of the form returned by \function{time.localtime()}. - The DST flag is -1. \code{\var{d}.timetuple()} is equivalent to + \code{\var{d}.timetuple()} is equivalent to \code{(\var{d}.year, \var{d}.month, \var{d}.day, \var{d}.hour, \var{d}.minute, \var{d}.second, - \var{d}.weekday(), \# 0 is Monday + \var{d}.weekday(), \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1, - \# day of year - -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 timetuple 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 - \method{date.toordinal()}. + \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 \method{date.weekday()}. + 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 \method{date.isoweekday()}. + 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 \method{date.isocalendar()}. + same as \code{self.date().isocalendar()}. \end{methoddesc} \begin{methoddesc}{isoformat}{sep='T'} Return a string representing the date and time in ISO 8601 format, YYYY-MM-DDTHH:MM:SS.mmmmmm - or, if self.microsecond is 0, + 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, - datetime(2002, 12, 4, 1, 2, 3, 4).isoformat(' ') == - '2002-12-04 01:02:03.000004' + +\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__}{} @@ -746,8 +845,9 @@ Instance methods: \end{methoddesc} \begin{methoddesc}{ctime}{} - Return a string representing the date, for example - datetime(2002, 12, 4, 20, 30, 40).ctime() == 'Wed Dec 4 20:30:40 2002'. + 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 @@ -765,22 +865,24 @@ Instance methods: \subsection{\class{time} Objects \label{datetime-time}} -A \class{time} object represents an idealized time of day, independent -of day and timezone. +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=0, minute=0, second=0, microsecond=0} - All arguments are optional. They may be ints or longs, in the - following ranges: +\begin{classdesc}{time}{hour=0, minute=0, second=0, microsecond=0, + tzinfo=None} + 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} + \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. + If an argument outside those ranges is given, + \exception{ValueError} is raised. \end{classdesc} Class attributes: @@ -817,12 +919,24 @@ Instance attributes (read-only): 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 time to time, where time1 is considered - less than time2 when time1 precedes time2 in time. + 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()}). \item hash, use as dict key @@ -831,22 +945,32 @@ Supported operations: efficient pickling \item - in Boolean contexts, a time object is considered to be true - if and only if it isn't equal to \code{time(0)} + 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}{hour=, minute=, second=, microsecond=} - Return a time with the same value, except for those fields given - new values by whichever keyword arguments are specified. +\begin{methoddesc}{replace}(hour=, minute=, second=, microsecond=, 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 + 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__}{} @@ -859,6 +983,21 @@ Instance methods: format string. See the section on \method{strftime()} behavior. \end{methoddesc} +\begin{methoddesc}{utcoffset}{} + If \member{tzinfo} is \code{None}, returns \code{None}, else + returns \code{tzinfo.utcoffset(self)}. +\end{methoddesc} + +\begin{methoddesc}{dst}{} + If \member{tzinfo} is \code{None}, returns \code{None}, else + returns \code{tzinfo.dst(self)}. +\end{methoddesc} + +\begin{methoddesc}{tzname}{} + If \member{tzinfo} is \code{None}, returns \code{None}, else + returns \code{tzinfo.tzname(self)}. +\end{methoddesc} + \subsection{\class{tzinfo} Objects \label{datetime-tzinfo}} @@ -870,8 +1009,8 @@ 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{datetimetz} and \class{timetz} objects. -The latter objects view their fields as being in local time, and the +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. @@ -909,7 +1048,7 @@ implement all of them. \begin{methoddesc}{dst}{self, dt} - Return the daylight savings time (DST) adjustment, in minutes east of + Return the daylight saving time (DST) adjustment, in minutes east of UTC, or \code{None} if DST information isn't known. Return \code{0} if DST is not in effect. If DST is in effect, return the offset as a @@ -918,10 +1057,10 @@ implement all of them. 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 displaying DST info separately. For - example, \method{datetimetz.timetuple()} calls its \member{tzinfo} + 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{datetimetz.astimezone()} calls \method{dst()} to account for + \method{datetime.astimezone()} calls \method{dst()} to account for DST changes when crossing time zones. An instance \var{tz} of a \class{tzinfo} subclass that models both @@ -929,16 +1068,17 @@ implement all of them. \code{tz.utcoffset(dt) - tz.dst(dt)} - must return the same result for every \class{datetimetz} \var{dt} + must return the same result for every \class{datetime} \var{dt} with \code{dt.tzinfo==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{datetimetz.astimezone()} relies on this, but + implementation of \method{datetime.astimezone()} relies on this, but cannot detect violations; it's the programmer's responsibility to ensure it. \begin{methoddesc}{tzname}{self, dt} - Return the timezone name corresponding to the \class{datetime} represented + Return the timezone name corresponding to the \class{datetime} + object represented by \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", @@ -952,21 +1092,21 @@ implement all of them. \end{methoddesc} -These methods are called by a \class{datetimetz} or \class{timetz} object, -in response to their methods of the same names. A \class{datetimetz} -object passes itself as the argument, and a \class{timetz} object passes +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{datetimetz}. +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 timetz objects don't participate in the +class wishes to say that time objects don't participate in the \class{tzinfo} protocol. In other applications, it may be more useful for \code{utcoffset(None)} to return the standard UTC offset. -When a \class{datetimetz} object is passed in response to a -\class{datetimetz} method, \code{dt.tzinfo} is the same object as +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, @@ -1024,440 +1164,10 @@ ambiguities when using UTC, or any other fixed-offset tzinfo subclass EDT (fixed offset -4 hours)). -\subsection{\class{timetz} Objects \label{datetime-timetz}} - -A time object represents a (local) time of day, independent of any -particular day, and subject to adjustment via a \class{tzinfo} object. - -Constructor: - -\begin{classdesc}{time}{hour=0, minute=0, second=0, microsecond=0, - tzinfo=None} - 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. -\end{classdesc} - -Class attributes: - -\begin{memberdesc}{min} - The earliest representable time, \code{timetz(0, 0, 0, 0)}. -\end{memberdesc} - -\begin{memberdesc}{max} - The latest representable time, \code{timetz(23, 59, 59, 999999)}. -\end{memberdesc} - -\begin{memberdesc}{resolution} - The smallest possible difference between non-equal \class{timetz} - objects, \code{timedelta(microseconds=1)}, although note that - arithmetic on \class{timetz} 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{timetz} - constructor, or \code{None} if none was passed. -\end{memberdesc} - -Supported operations: - -\begin{itemize} - \item - comparison of \class{timetz} to \class{time} or \class{timetz}, - 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()}). - - \item - hash, use as dict key - - \item - pickling - - \item - in Boolean contexts, a \class{timetz} 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}(hour=, minute=, second=, microsecond=, tzinfo=) - Return a \class{timetz} with the same value, except for those fields given - new values by whichever keyword arguments are specified. Note that - \code{tzinfo=None} can be specified to create a naive \class{timetz} from an - aware \class{timetz}. -\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 \class{timetz} \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 the section on \method{strftime()} behavior. -\end{methoddesc} - -\begin{methoddesc}{utcoffset}{} - If \member{tzinfo} is \code{None}, returns \code{None}, else - \code{tzinfo.utcoffset(self)} converted to a \class{timedelta} - object. -\end{methoddesc} - -\begin{methoddesc}{tzname}{} - If \member{tzinfo} is \code{None}, returns \code{None}, else - \code{tzinfo.tzname(self)}. -\end{methoddesc} - -\begin{methoddesc}{dst}{} - If \member{tzinfo} is \code{None}, returns \code{None}, else - \code{tzinfo.dst(self)} converted to a \class{timedelta} object. -\end{methoddesc} - - - -\subsection{ \class{datetimetz} Objects \label{datetime-datetimetz}} - -\begin{notice}[warning] - I think this is \emph{still} missing some methods from the - Python implementation. -\end{notice} - -A \class{datetimetz} object is a single object containing all the information -from a \class{date} object and a \class{timetz} object. - -Constructor: - -\begin{classdesc}{datetimetz}{year, month, day, - hour=0, minute=0, second=0, microsecond=0, - tzinfo=None} - 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 (class methods): - -\begin{funcdesc}{today}{} -\methodline{utcnow}{} -\methodline{utcfromtimestamp}{timestamp} -\methodline{fromordinal}{ordinal} - These are the same as the \class{datetime} class methods of the - same names, except that they construct a \class{datetimetz} - object, with tzinfo \code{None}. -\end{funcdesc} - -\begin{funcdesc}{now}{\optional{tzinfo=None}} -\methodline{fromtimestamp}{timestamp\optional{, tzinfo=None}} - These are the same as the \class{datetime} class methods of the - same names, except that they accept an additional, optional tzinfo - argument, and construct a \class{datetimetz} object with that - \class{tzinfo} object attached. -\end{funcdesc} - -\begin{funcdesc}{combine}{date, time} - This is the same as \method{datetime.combine()}, except that it - constructs a \class{datetimetz} object, and, if the time object is - of type timetz, the \class{datetimetz} object has the same - \class{tzinfo} object as the time object. -\end{funcdesc} - -Class attributes: - -\begin{memberdesc}{min} - The earliest representable \class{datetimetz}, - \code{datetimetz(MINYEAR, 1, 1)}. -\end{memberdesc} - -\begin{memberdesc}{max} - The latest representable \class{datetime}, - \code{datetimetz(MAXYEAR, 12, 31, 23, 59, 59, 999999)}. -\end{memberdesc} - -\begin{memberdesc}{resolution} - The smallest possible difference between non-equal \class{datetimetz} - objects, \code{timedelta(microseconds=1)}. -\end{memberdesc} - -Instance attributes, all 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{datetimetz} constructor, or \code{None} if none was passed. -\end{memberdesc} - -Supported operations: - -\begin{itemize} - \item - datetimetz1 + timedelta -> datetimetz2 - timedelta + datetimetz1 -> datetimetz2 - - The same as addition of \class{datetime} objects, except that - datetimetz2.tzinfo is set to datetimetz1.tzinfo. - - \item - datetimetz1 - timedelta -> datetimetz2 - - The same as addition of \class{datetime} objects, except that - datetimetz2.tzinfo is set to datetimetz1.tzinfo. - - \item - aware_datetimetz1 - aware_datetimetz2 -> timedelta - naive_datetimetz1 - naive_datetimetz2 -> timedelta - naive_datetimetz1 - datetime2 -> timedelta - datetime1 - naive_datetimetz2 -> timedelta - - Subtraction of a \class{datetime} or \class{datetimetz}, from a - \class{datetime} or \class{datetimetz}, 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, subtraction acts as for \class{datetime} subtraction. - - 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 UTC - datetimes (by subtracting \code{a.utcoffset()} minutes from \var{a}, - and \code{b.utcoffset()} minutes from \var{b}), and then doing - \class{datetime} subtraction, except that the implementation never - overflows. - - \item - comparison of \class{datetimetz} to \class{datetime} or - \class{datetimetz}, 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 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()}). - - \item - hash, use as dict key - - \item - efficient pickling - - \item - in Boolean contexts, all \class{datetimetz} objects are considered to be - true -\end{itemize} - -Instance methods: - -\begin{methoddesc}{date}{} -\methodline{time}{} -\methodline{toordinal}{} -\methodline{weekday}{} -\methodline{isoweekday}{} -\methodline{isocalendar}{} -\methodline{ctime}{} -\methodline{__str__}{} -\methodline{strftime}{format} - These are the same as the \class{datetime} methods of the same names. -\end{methoddesc} - -\begin{methoddesc}{timetz}{} - Return \class{timetz} object with same hour, minute, second, microsecond, - and tzinfo. -\end{methoddesc} - -\begin{methoddesc}{replace}{year=, month=, day=, hour=, minute=, second=, - microsecond=, tzinfo=} - Return a datetimetz with the same value, except for those fields given - new values by whichever keyword arguments are specified. Note that - \code{tzinfo=None} can be specified to create a naive datetimetz from - an aware datetimetz. -\end{methoddesc} - -\begin{methoddesc}{astimezone}{tz} - Return a \class{datetimetz} object with new \member{tzinfo} member - \var{tz}. - \var{tz} must be \code{None}, or an instance of a \class{tzinfo} subclass. - If \var{tz} is \code{None}, \var{self} is naive, - \code{tz.utcoffset(self)} returns \code{None}, - or \code{self.tzinfo}\ is \var{tz}, - \code{self.astimezone(tz)} is equivalent to - \code{self.replace(tzinfo=tz)}: a new timezone object is attached - without any conversion of date or time fields. Else \code{self.tzinfo} - and \var{tz} must implement the \method{utcoffset()} and \method{dst()} - \class{tzinfo} methods, and the date and time fields are adjusted so - that the result is local time in time zone \var{tz}, representing the - same UTC time as \var{self}: after \code{astz = dt.astimezone(tz)}, - \code{astz - astz.utcoffset()} will usually have the same date and time - members as \code{dt - 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). -\end{methoddesc} - -\begin{methoddesc}{utcoffset}{} - If \member{tzinfo} is \code{None}, returns \code{None}, else - \code{tzinfo.utcoffset(self)} converted to a \class{timedelta} - object. -\end{methoddesc} - -\begin{methoddesc}{tzname}{} - If \member{tzinfo} is \code{None}, returns \code{None}, else - returns \code{tzinfo.tzname(self)}. -\end{methoddesc} - -\begin{methoddesc}{dst}{} - If \member{tzinfo} is \code{None}, returns \code{None}, else - \code{tzinfo.dst(self)} converted to a \class{timedelta} - object. -\end{methoddesc} - -\begin{methoddesc}{timetuple}{} - Like \function{datetime.timetuple()}, but sets the - \member{tm_isdst} flag according to the \method{dst()} method: if - \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{datetimetz} 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()} minutes, and a timetuple for the - normalized time is returned. \member{tm_isdst} is forced to 0. - Note that the result's \member{tm_year} field 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}{isoformat}{sep='T'} - 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 * ->>> class TZ(tzinfo): -... def utcoffset(self, dt): return timedelta(minutes=-399) -... ->>> datetimetz(2002, 12, 25, tzinfo=TZ()).isoformat(' ') -'2002-12-25 00:00:00-06:39' -\end{verbatim} -\end{methoddesc} - -\code{str(\var{d})} is equivalent to \code{\var{d}.isoformat(' ')}. - - \subsection{\method{strftime()} Behavior} -\class{date}, \class{datetime}, \class{datetimetz}, \class{time}, -and \class{timetz} objects all support a \code{strftime(\var{format})} +\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)} @@ -1465,7 +1175,7 @@ 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} and \class{timetz} objects, the format codes for +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. |