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
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}
\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}
\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
timedelta
tzinfo
time
- timetz
date
datetime
- datetimetz
\end{verbatim}
\subsection{\class{timedelta} Objects \label{datetime-timedelta}}
\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
\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
\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
\item
date1 - date2 -> timedelta
+
This is exact, and cannot overflow. timedelta.seconds and
timedelta.microseconds are 0, and date2 + timedelta == date1
after.
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)}.
\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}
\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}
\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}
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.
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}
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}
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
\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__}{}
\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
\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:
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
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__}{}
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}}
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.
\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
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
\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",
\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,
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)}
\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.
projects / python / commitdiff