[Python-checkins] python/nondist/sandbox/datetime doc.txt,1.51,1.52
tim_one@users.sourceforge.net
tim_one@users.sourceforge.net
Sat, 14 Dec 2002 18:52:54 -0800
Update of /cvsroot/python/python/nondist/sandbox/datetime
In directory sc8-pr-cvs1:/tmp/cvs-serv31865
Modified Files:
doc.txt
Log Message:
Added datetimetz docs. No, this never ends.
Index: doc.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/datetime/doc.txt,v
retrieving revision 1.51
retrieving revision 1.52
diff -C2 -d -r1.51 -r1.52
*** doc.txt 13 Dec 2002 19:00:54 -0000 1.51
--- doc.txt 15 Dec 2002 02:52:51 -0000 1.52
***************
*** 74,96 ****
Overview
========
! The datetime module supplies a number of 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.
class date
year, month, and day
! This is an idealized date, assuming the current Gregorian calendar
always was, and always will be, in effect.
class time
hour, minute, second, and microsecond
! This is independent of any particular day.
class datetime
year, month, day, hour, minute, second, and microsecond
! This has no concept of timezone or daylight savings time. You
! can think of a datetime object as representing UTC time, or local
! time, or whatever else is convenient.
class timedelta
--- 74,115 ----
Overview
========
! The 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.
!
! There are two kinds of date and time objects: "naive" and "aware".
! These refer to whether they have any notion of time zone, daylight
! savings time, or other kind of algorithmic or political time adjustment.
! Whether a naive datetime object represents 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 datetime objects are easy to understand and to work with,
! at the cost of ignoring some aspects of reality.
!
! For applications requiring more, so-called aware datetime subclasses add
! an optional time zone information object to the basic naive classes.
! These tzinfo objects capture information about offset from UTC time,
! time zone name, and whether DST is in effect. Note that no concrete
! tzinfo classes are supplied by the datetime module. Instead, they
! provide a framework for incorporating the level of detail an app may
! require. The rules for time adjustment across the world are more
! political than rational, and there is no standard suitable for every
! app.
class date
year, month, and day
! An idealized naive date, assuming the current Gregorian calendar
always was, and always will be, in effect.
class time
hour, minute, second, and microsecond
! 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).
class datetime
year, month, day, hour, minute, second, and microsecond
! A combination of a naive date and a naive time.
class timedelta
***************
*** 104,113 ****
and/or daylight savings time).
- class datetimetz
- Like datetime, but also supports a customizable notion of time
- adjustment.
-
class timetz
! Like time, but also supports a customizable notion of time adjustment.
Objects of these types are immutable.
--- 123,133 ----
and/or daylight savings time).
class timetz
! An aware subclass of time, supporting a customizable notion of
! time adjustment.
!
! class datetimetz
! An aware subclass of datetime, supporting a customizable notion of
! time adjustment.
Objects of these types are immutable.
***************
*** 119,127 ****
timedelta
tzinfo
date
datetime
datetimetz
- time
- timetz
--- 139,147 ----
timedelta
tzinfo
+ time
+ timetz
date
datetime
datetimetz
***************
*** 130,138 ****
MINYEAR
The smallest year number allowed in a date, datetime, or datetimetz
! object.
MAXYEAR
The largest year number allowed in a date, datetime, or datetimetz
! object.
--- 150,158 ----
MINYEAR
The smallest year number allowed in a date, datetime, or datetimetz
! object. MINYEAR is 1.
MAXYEAR
The largest year number allowed in a date, datetime, or datetimetz
! object. MAXYEAR is 9999.
***************
*** 140,144 ****
===============
A timedelta object represents a duration, the difference between two
! datetimes.
Constructor:
--- 160,164 ----
===============
A timedelta object represents a duration, the difference between two
! dates or times.
Constructor:
***************
*** 168,172 ****
If any argument is a float, and there are fractional microseconds,
the fractional microseconds left over from all arguments are combined
! and their sum is rounded to the nearest microsecond.
If the normalized value of days lies outside the indicated range,
--- 188,194 ----
If any argument is a float, and there are fractional microseconds,
the fractional microseconds left over from all arguments are combined
! and their sum is rounded to the nearest microsecond. If no
! argument is a flost, the conversion and normalization processes
! are exact (no information is lost).
If the normalized value of days lies outside the indicated range,
***************
*** 196,199 ****
--- 218,224 ----
objects, timedelta(microseconds=1).
+ Note that, because of normalization, timedelta.max > -timedelta.min.
+ -timedelta.max is not representable as a timedelta object.
+
Instance attributes (read-only):
***************
*** 222,232 ****
is true.
- - certain additions and subtractions with date, datetime, and datimetz
- objects (see below)
-
- timedelta // (int or long) -> timedelta
The floor is computed and the remainder (if any) is thrown away.
Division by 0 raises ZeroDivisionError.
- +timedelta -> timedelta
Returns a timedelta object with the same value.
--- 247,257 ----
is true.
- timedelta // (int or long) -> timedelta
The floor is computed and the remainder (if any) is thrown away.
Division by 0 raises ZeroDivisionError.
+ - certain additions and subtractions with date, datetime, and datimetz
+ objects (see below)
+
- +timedelta -> timedelta
Returns a timedelta object with the same value.
***************
*** 279,288 ****
- today()
-
Return the current local date. This is equivalent to
date.fromtimestamp(time.time()).
- fromtimestamp(timestamp)
-
Return the local date corresponding to the POSIX timestamp, such as
is returned by time.time(). This may raise ValueError, if the
--- 304,311 ----
***************
*** 292,296 ****
- fromordinal(ordinal)
-
Return the date corresponding to the proleptic Gregorian ordinal,
where January 1 of year 1 has ordinal 1. ValueError is raised
--- 315,318 ----
***************
*** 415,420 ****
- strftime(format)
Return a string representing the date, controlled by an explicit
! format string. Formats referring to hours, minutes or seconds will
! see 0 values. d.strftime(f) is the same as
time.strftime(f, d.timetuple()).
--- 437,442 ----
- strftime(format)
Return a string representing the date, controlled by an explicit
! format string. Format codes referring to hours, minutes or seconds
! will see 0 values. d.strftime(f) is the same as
time.strftime(f, d.timetuple()).
***************
*** 448,452 ****
- today()
-
Return the current local datetime. This is equivalent to
datetime.fromtimestamp(time.time()).
--- 470,473 ----
***************
*** 454,458 ****
- now()
-
Return the current local datetime. This is like today(), but, if
possible, supplies more precision than can be gotten from going
--- 475,478 ----
***************
*** 462,466 ****
- utcnow()
-
Return the current UTC datetime. This is like now(), but returns
the current UTC date and time.
--- 482,485 ----
***************
*** 468,472 ****
- fromtimestamp(timestamp)
-
Return the local datetime corresponding to the POSIX timestamp, such
as is returned by time.time(). This may raise ValueError, if the
--- 487,490 ----
***************
*** 477,481 ****
- utcfromtimestamp(timestamp)
-
Return the UTC datetime corresponding to the POSIX timestamp.
This may raise ValueError, if the timestamp is out of the range of
--- 495,498 ----
***************
*** 485,489 ****
- fromordinal(ordinal)
-
Return the datetime corresponding to the proleptic Gregorian ordinal,
where January 1 of year 1 has ordinal 1. ValueError is raised
--- 502,505 ----
***************
*** 492,500 ****
- combine(date, time)
-
Return a new datetime object whose date components are equal to the
given date object's, and whose time components are equal to the given
time object's. For any datetime object d,
d == datetime.combine(d.date(), d.time()).
Class attributes:
--- 508,518 ----
- combine(date, time)
Return a new datetime object whose date components are equal to the
given date object's, and whose time components are equal to the given
time object's. For any datetime object d,
d == datetime.combine(d.date(), d.time()).
+ If date is a datetime or datetimetz object, its time components are
+ ignored. If date is datetimetz object, its tzinfo component is also
+ ignored. If time is a timetz object, its tzinfo component is ignored.
Class attributes:
***************
*** 533,537 ****
MINYEAR or larger than MAXYEAR.
! - date1 - timedelta -> date2
Computes the datetime2 such that datetime2 + timedelta == datetime1.
This isn't quite equivalent to datetime1 + (-timedelta), because
--- 551,555 ----
MINYEAR or larger than MAXYEAR.
! - datetime1 - timedelta -> datetime2
Computes the datetime2 such that datetime2 + timedelta == datetime1.
This isn't quite equivalent to datetime1 + (-timedelta), because
***************
*** 555,559 ****
- date()
! Return new date object with same year, month and day.
- time()
--- 573,577 ----
- date()
! Return date object with same year, month and day.
- time()
***************
*** 647,651 ****
.resolution
The smallest possible difference between non-equal time
! objects, timedelta(microseconds=1).
Instance attributes (read-only):
--- 665,670 ----
.resolution
The smallest possible difference between non-equal time
! objects, timedelta(microseconds=1), although note that
! arithmetic on time objects is not supported.
Instance attributes (read-only):
***************
*** 689,713 ****
============
tzinfo is an abstract base clase, meaning that objects directly of this
! class should not be instantiated. You need to derive a concrete subclass,
! and supply implementations of (at least) the standard tzinfo methods. The
! datetime module does not supply any concrete subclasses of tzinfo.
An instance of (a concrete subclass of) tzinfo can be passed to the
constructors for datetimetz and timetz objects. The latter objects
view their fields as being in local time, and the 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.
!
! A concrete subclass of tzinfo must implement the following methods.
!
! - __init__()
! There are no special requirements on the constructor.
! tzinfo.__init__() should not be called, since tzinfo is an
! abstract class.
! The remaining methods are normally called by a datetimetz or timetz object,
! in response to their methods of the same names, passing itself as the
! argument. If dt.tzinfo is not None and not equal to self, an exception
! should be raised:
- utcoffset(dt)
--- 708,731 ----
============
tzinfo is an abstract base clase, meaning that objects directly of this
! class should not be instantiated. You need to derive a concrete
! subclass, and (at least) supply implementations of the standard tzinfo
! methods needed by the datetime methods you use. The datetime module does
! not supply any concrete subclasses of tzinfo.
An instance of (a concrete subclass of) tzinfo can be passed to the
constructors for datetimetz and timetz objects. The latter objects
view their fields as being in local time, and the 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.
! A concrete subclass of tzinfo may need to implement the following
! methods. Exactly which methods are needed depends on the uses made
! of aware datetime objects; if in doubt, simply implement all of them.
! The methods are called by a datetimetz or timetz object, passing itself
! as the argument. A tzinfo subclass's methods should be prepared to
! accept a dt argument of type None, timetz, or datetimetz. If is not
! None, and dt.tzinfo is not None and not equal to self, an exception
! should be raised.
- utcoffset(dt)
***************
*** 722,735 ****
- tzname(dt)
! Return the timezone name corresponding to the date and time
! represented by dt, as a string. Nothing about string names is
! defined by the datetime module, and there's no requirement that
! it mean anything in particular. For example, "GMT", "UTC", "-500",
! "-5:00", "EDT", "US/Eastern", "America/New York" are all valid
! replies. Return None if a string name isn't known. Note that
! this is a method rather than a fixed string primarily because
! some tzinfo objects will wish to return different names depending
! on the specific value of dt passed, especially if the tzinfo class
! is accounting for DST.
- dst(dt)
--- 740,752 ----
- tzname(dt)
! Return the timezone name corresponding to the datetime represented
! by dt, as a string. Nothing about string names is defined by the
! datetime module, and there's no requirement that it mean anything
! in particular. For example, "GMT", "UTC", "-500", "-5:00", "EDT",
! "US/Eastern", "America/New York" are all valid replies. Return
! None if a string name isn't known. Note that this is a method
! rather than a fixed string primarily because some tzinfo objects
! will wish to return different names depending on the specific value
! of dt passed, especially if the tzinfo class is accounting for DST.
- dst(dt)
***************
*** 741,744 ****
--- 758,816 ----
separately.
+ Example tzinfo classes:
+
+ class UTC(tzinfo):
+ "UTC"
+ def utcoffset(self, dt):
+ return 0
+ def tzname(self, dt):
+ return "UTC"
+ def dst(self, dt):
+ return 0
+
+ class FixedOffset(tzinfo):
+ "Fixed offset in minutes east from UTC"
+ def __init__(self, offset, name):
+ self.__offset = offset
+ self.__name = name
+ def utcoffset(self, dt):
+ return self.__offset
+ def tzname(self, dt):
+ return self.__name
+ def dst(self, dt):
+ # It depends on more than we know in an example.
+ return None # Indicate we don't know
+
+ import time
+ class LocalTime(tzinfo):
+ "Local time as defined by the operating system"
+ def _isdst(self, dt):
+ t = (dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second,
+ -1, -1, -1)
+ # XXX This may fail for years < 1970 or >= 2038
+ t = time.localtime(time.mktime(t))
+ return t.tm_isdst > 0
+ def utcoffset(self, dt):
+ if self._isdst(dt):
+ return -time.timezone/60
+ else:
+ return -time.altzone/60
+ def tzname(self, dt):
+ return time.tzname[self._isdst(dt)]
+
+
+ Naive and Aware Objects
+ =======================
+ Objects directly of these types are always naive: date, datetime, and
+ time.
+
+ An object d of type timetz or datetimetz may be naive or aware. d
+ is aware if d.tzinfo is not None, and d.tzinfo.utcoffset(d) does
+ not return None. If d.tzinfo is None, or if d.tzinfo is not None
+ but d.tzinfo.utcoffset(d) returns None, d is naive.
+
+ The distinction between naive and aware doesn't apply to timedelta
+ objects.
+
class timetz
***************
*** 776,780 ****
.resolution
The smallest possible difference between non-equal timetz
! objects, timedelta(microseconds=1).
Instance attributes (read-only):
--- 848,853 ----
.resolution
The smallest possible difference between non-equal timetz
! objects, timedelta(microseconds=1), although note that
! arithmetic on timetz objects is not supported.
Instance attributes (read-only):
***************
*** 784,788 ****
.second in range(60)
.microsecond in range(1000000)
! .tzinfo the object passed as the tzinfo= argument to the
timetz constructor, or None if none was passed.
--- 857,861 ----
.second in range(60)
.microsecond in range(1000000)
! .tzinfo the object passed as the tzinfo argument to the
timetz constructor, or None if none was passed.
***************
*** 809,815 ****
or, if self.microsecond is 0
HH:MM:SS
! If self.tzinfo.utcoffset(self) does not return None, a 6-character
! string is appended, giving the UCT offset in (signed) hours and
! minutes:
HH:MM:SS.mmmmmm+HH:MM
or, if self.microsecond is 0
--- 882,887 ----
or, if self.microsecond is 0
HH:MM:SS
! If self.utcoffset() does not return 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
***************
*** 824,838 ****
second and time zone should not be used, since a timetz object has
meaningful values only for those fields.
! Format code %Z: If self.tzinfo is None, or if
! self.tzinfo.tzname(self) returns None, %Z is replaced by an empty
! string. Else %Z is replaced by the returned value, which must be
! a string.
Format code %z: This is an extension to the usual set of format
! codes. If self.tzinfo is None, or if self.tzinfo.uctoffset(self)
! returns None, %z is replaced by an empty string. Else the return
! value is transformed into a 5-character string of the form +HHMM or
! -HHMM, and replaces %z, where HH is a 2-digit string giving the
! number of UTC offset hours, and MM is a 2-digit string giving the
! number of UTC offset minutes.
XXX Sheesh. This needs an example.
--- 896,908 ----
second and time zone should not be used, since a timetz object has
meaningful values only for those fields.
! Format code %Z: If self.tzname() returns None, %Z is replaced by
! an empty string. Else %Z is replaced by the returned value, which
! must be a string.
Format code %z: This is an extension to the usual set of format
! codes. If self.uctoffset() returns None, %z is replaced by an empty
! string. Else the return value is transformed into a 5-character
! string of the form +HHMM or -HHMM, and replaces %z, where HH is a
! 2-digit string giving the number of UTC offset hours, and MM is a
! 2-digit string giving the number of UTC offset minutes.
XXX Sheesh. This needs an example.
***************
*** 849,852 ****
--- 919,1105 ----
class datetimetz
================
+ XXX I think this is *still* missing some methods from the
+ XXX Python implementation.
+ A datetimetz object is a single object containing all the information
+ from a date object and a timetz object.
+
+ Constructor:
+
+ datetimetz(year, month, day,
+ hour=0, minute=0, second=0, microsecond=0, tzinfo=None)
+
+ The year, month and day arguments are required. tzinfo may be None,
+ or an instance of a tzinfo subclass. The remaining arguments may be
+ ints or longs, in the following ranges:
+
+ MINYEAR <= year <= MAXYEAR
+ 1 <= month <= 12
+ 1 <= day <= number of days in the given month and year
+ 0 <= hour < 24
+ 0 <= minute < 60
+ 0 <= second < 60
+ 0 <= microsecond < 1000000
+
+ If an argument outside those ranges is given, ValueError is raised.
+
+ Other constructors (class methods):
+
+ - today()
+ utcnow()
+ utcfromtimestamp(timestamp)
+ fromordinal(ordinal)
+
+ These are the same as the datetime class methods of the same names,
+ except that they construct a datetimetz object, with tzinfo None.
+
+ - now([tzinfo=None])
+ fromtimestamp(timestamp[, tzinfo=None])
+
+ These are the same as the datetime class methods of the same names,
+ except that they accept an additional, optional tzinfo argument, and
+ construct a datetimetz object with that tzinfo object attached.
+
+ - combine(date, time)
+ This is the same as datetime.combine(), except that it constructs
+ a datetimetz object, and, if the time object is of type timetz,
+ the datetimetz object has the same tzinfo object as the time object.
+
+ Class attributes:
+
+ .min
+ The earliest representable datetimetz,
+ datetimetz(MINYEAR, 1, 1).
+
+ .max
+ The latest representable datetime,
+ datetimetz(MAXYEAR, 12, 31, 23, 59, 59, 999999).
+
+ .resolution
+ The smallest possible difference between non-equal datetimetz
+ objects, timedelta(microseconds=1).
+
+ Instance attributes (read-only):
+
+ .year between MINYEAR and MAXYEAR inclusive
+ .month between 1 and 12 inclusive
+ .day between 1 and the number of days in the given month
+ of the given year
+ .hour in range(24)
+ .minute in range(60)
+ .second in range(60)
+ .microsecond in range(1000000)
+ .tzinfo the object passed as the tzinfo argument to the
+ datetimetz constructor, or None if none was passed.
+
+ Supported operations:
+
+ - datetimetz1 + timedelta -> datetimetz2
+ timedelta + datetimetz1 -> datetimetz2
+ The same as addition of datetime objects, except that
+ datetimetz2.tzinfo is set to datetimetz1.tzinfo.
+
+ - datetimetz1 - timedelta -> datetimetz2
+ The same as addition of datetime objects, except that
+ datetimetz2.tzinfo is set to datetimetz1.tzinfo.
+
+ - aware_datetimetz1 - aware_datetimetz2 -> timedelta
+ naive_datetimetz1 - naive_datetimetz2 -> timedelta
+ naive_datetimetz1 - datetime2 -> timedelta
+ datetime1 - naive_datetimetz2 -> timedelta
+
+ Subtraction of a datetime or datetimetz, from a datetime or
+ datetimetz, is defined only if both operands are naive, or if
+ both are aware. If one is aware and the other is naive, TypeError
+ is raised.
+
+ If both are naive, subtraction acts as for datetime subtraction.
+
+ If both are aware datetimetz objects, a-b acts as if a and b were
+ first converted to UTC datetimes (by subtracting a.utcoffset()
+ minutes from a, and b.utcoffset() minutes from b), and then doing
+ datetime subtraction, except that the implementation never
+ overflows.
+
+ - Comparison of datetimetz to datetime or datetimetz. As for
+ subtraction, comparison is defined only if both operands are
+ naive or both are aware. If both are naive, comparison is as
+ for datetime objects with the same date and time components.
+ If both are aware, comparison acts as if both were converted to
+ UTC datetimes first, except the the implementation never
+ overflows. If one comparand is naive and the other aware,
+ TypeError is raised.
+
+ - hash, use as dict key
+
+ - efficient pickling
+
+ - in Boolean contexts, all datetimetz objects are considered to be
+ true
+
+ Instance methods:
+
+ - date()
+ time()
+ toordinal()
+ weekday()
+ isoweekday()
+ isocalendar()
+ ctime()
+ __str__()
+
+ These are the same as the datetime methods of the same names.
+
+ - timetz()
+ Return timetz object with same hour, minute, second, microsecond,
+ and tzinfo.
+
+ - utcoffset()
+ If self.tzinfo is None, returns None, else self.tzinfo.utcoffset(self).
+
+ - tzname():
+ If self.tzinfo is None, returns None, else self.tzinfo.tzname(self).
+
+ - dst()
+ If self.tzinfo is None, returns None, else self.tzinfo.dst(self).
+
+ - timetuple()
+ XXX This should use self.dst() to fill in the DST flag.
+ Return a 9-element tuple of the form returned by time.localtime().
+ The DST flag is -1. 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)
+
+ - 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,
+ YYYY-MM-DDTHH:MM:SS
+
+ If self.utcoffset() does not return 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 self.microsecond is 0
+ YYYY-MM-DDTHH:MM:SS+HH:MM
+
+ Optional argument sep (default 'T') is a one-character separator,
+ placed between the date and time portions of the result. For example,
+
+ >>> from datetime import *
+ >>> class TZ(tzinfo):
+ ... def utcoffset(self, dt): return -399
+ ...
+ >>> datetimetz(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
+ '2002-12-25 00:00:00-06:39'
+ >>>
+
+ str(d) is equivalent to d.isoformat(' ').
+
+ - strftime(format)
+ Return a string representing the date and time, controlled by an
+ explicit format string. See timetz.strftime() for the treatment
+ of the %Z and %z format codes.