[Python-checkins] python/dist/src/Doc/lib libdatetime.tex,1.16,1.17
fdrake@users.sourceforge.net
fdrake@users.sourceforge.net
Mon, 30 Dec 2002 13:26:44 -0800
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv16608
Modified Files:
libdatetime.tex
Log Message:
We're using strictly American spellings, so there's no diaresis over
the i in naive.
More markup fixups.
Index: libdatetime.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdatetime.tex,v
retrieving revision 1.16
retrieving revision 1.17
diff -C2 -d -r1.16 -r1.17
*** libdatetime.tex 30 Dec 2002 20:52:32 -0000 1.16
--- libdatetime.tex 30 Dec 2002 21:26:42 -0000 1.17
***************
*** 13,18 ****
\versionadded{2.3}
- \newcommand{\Naive}{Na\"ive}
- \newcommand{\naive}{na\"ive}
The \module{datetime} module supplies classes for manipulating dates
--- 13,16 ----
***************
*** 21,36 ****
efficient field 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
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.
These \class{tzinfo} objects capture information about the offset from
UTC time, the time zone name, and whether Daylight Savings Time is in
--- 19,34 ----
efficient field 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
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.
These \class{tzinfo} objects capture information about the offset from
UTC time, the time zone name, and whether Daylight Savings Time is in
***************
*** 62,66 ****
\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}.
--- 60,64 ----
\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}.
***************
*** 68,72 ****
\begin{classdesc*}{time}
! An idealized {\naive} time, independent of any particular day, assuming
that every day has exactly 24*60*60 seconds (there is no notion
of "leap seconds" here).
--- 66,70 ----
\begin{classdesc*}{time}
! An idealized naive time, independent of any particular day, assuming
that every day has exactly 24*60*60 seconds (there is no notion
of "leap seconds" here).
***************
*** 76,80 ****
\begin{classdesc*}{datetime}
! A combination of a {\naive} date and a {\naive} time.
Attributes: \member{year}, \member{month}, \member{day},
\member{hour}, \member{minute}, \member{second},
--- 74,78 ----
\begin{classdesc*}{datetime}
! A combination of a naive date and a naive time.
Attributes: \member{year}, \member{month}, \member{day},
\member{hour}, \member{minute}, \member{second},
***************
*** 108,121 ****
Objects of the \class{date}, \class{datetime}, and \class{time} types
! are always \naive.
! An object \code{D} of type \class{timetz} or \class{datetimetz} may be
! {\naive} or aware. \code{D} is aware if \code{D.tzinfo} is not
! \code{None}, and \code{D.tzinfo.utcoffset(D)} does not return
! \code{None}. If \code{D.tzinfo} is \code{None}, or if \code{D.tzinfo}
! is not \code{None} but \code{D.tzinfo.utcoffset(D)} returns
! \code{None}, \code{D} is \naive.
! The distinction between {\naive} and aware doesn't apply to
\code{timedelta} objects.
--- 106,120 ----
Objects of the \class{date}, \class{datetime}, and \class{time} types
! are always naive.
! An object \var{d} of type \class{timetz} or \class{datetimetz} 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
\code{timedelta} objects.
***************
*** 194,199 ****
\end{tableii}
! Note that, because of normalization, timedelta.max > -timedelta.min.
! -timedelta.max is not representable as a \class{timedelta} object.
Instance attributes (read-only):
--- 193,199 ----
\end{tableii}
! 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):
***************
*** 284,288 ****
1 is called day number 2, and so on. This matches the definition of the
"proleptic Gregorian" calendar in Dershowitz and Reingold's book
! "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.
--- 284,288 ----
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.
***************
*** 410,419 ****
\function{time.localtime()}. The hours, minutes and seconds are
0, and the DST flag is -1.
! d.timetuple() is equivalent to
! (d.year, d.month, d.day,
! 0, 0, 0, \# h, m, s
! d.weekday(), \# 0 is Monday
! d.toordinal() - date(d.year, 1, 1).toordinal() + 1, \# day of year
! -1)
\end{methoddesc}
\begin{methoddesc}{toordinal}{}
--- 410,420 ----
\function{time.localtime()}. The hours, minutes and seconds are
0, and the DST flag is -1.
! \code{\var{d}.timetuple()} is equivalent to
! \code{(\var{d}.year, \var{d}.month, \var{d}.day,
! 0, 0, 0, \# h, m, s
! \var{d}.weekday(), \# 0 is Monday
! \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
! \# day of year
! -1)}
\end{methoddesc}
\begin{methoddesc}{toordinal}{}
***************
*** 466,470 ****
Return a string representing the date, for example
date(2002, 12, 4).ctime() == 'Wed Dec 4 00:00:00 2002'.
! d.ctime() is equivalent to time.ctime(time.mktime(d.timetuple()))
on platforms where the native C \cfunction{ctime()} function
(which \function{time.ctime()} invokes, but which
--- 467,472 ----
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
***************
*** 559,569 ****
\begin{methoddesc}{combine}{date, time}
Return a new \class{datetime} object whose date components 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
! d, d == datetime.combine(d.date(), 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}
--- 561,572 ----
\begin{methoddesc}{combine}{date, time}
Return a new \class{datetime} object whose date components 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}
***************
*** 596,601 ****
\begin{memberdesc}{day}
! Between 1 and the number of days in the given month
! of the given year.
\end{memberdesc}
--- 599,603 ----
\begin{memberdesc}{day}
! Between 1 and the number of days in the given month of the given year.
\end{memberdesc}
***************
*** 680,689 ****
Return a 9-element tuple of the form returned by
\function{time.localtime()}.
! The DST flag is -1. \code{d.timetuple()} is equivalent to
! (d.year, d.month, d.day,
! d.hour, d.minute, d.second,
! d.weekday(), \# 0 is Monday
! d.toordinal() - date(d.year, 1, 1).toordinal() + 1, \# day of year
! -1)
\end{methoddesc}
--- 682,692 ----
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}.year, \var{d}.month, \var{d}.day,
! \var{d}.hour, \var{d}.minute, \var{d}.second,
! \var{d}.weekday(), \# 0 is Monday
! \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
! \# day of year
! -1)}
\end{methoddesc}
***************
*** 811,815 ****
\item
in Boolean contexts, a time object is considered to be true
! if and only if it isn't equal to time(0)
\end{itemize}
--- 814,818 ----
\item
in Boolean contexts, a time object is considered to be true
! if and only if it isn't equal to \code{time(0)}
\end{itemize}
***************
*** 989,993 ****
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}
--- 992,996 ----
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}
***************
*** 1015,1019 ****
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}
--- 1018,1022 ----
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}
***************
*** 1184,1197 ****
\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.
--- 1187,1200 ----
\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.
***************
*** 1299,1303 ****
\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
--- 1302,1306 ----
\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
***************
*** 1363,1367 ****
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.
--- 1366,1370 ----
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.