6.9.3 date Objects
A date object represents a date (year, month and day) in an
idealized calendar, the current Gregorian calendar indefinitely extended in both directions.
January 1 of year 1 is called day number 1, January 2 of year 1 is called day number 2, and so
on. This matches the definition of the "proleptic Gregorian" calendar in Dershowitz
and Reingold's book 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.
-
| class date( |
year, month, day) |
- All arguments are required. Arguments may be ints or longs, in the following ranges:
MINYEAR <= year <= MAXYEAR1 <= month <= 121 <= day <= number of days in the given month and year
If an argument outside those ranges is given, ValueError is
raised.
Other constructors, all class methods:
-
- 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 timestamp is out of the range of values supported by the platform C localtime() function. It's common for this to be restricted to
years from 1970 through 2038. Note that on non-POSIX systems that include leap seconds in
their notion of a timestamp, leap seconds are ignored by fromtimestamp().
-
- Return the date corresponding to the proleptic Gregorian ordinal, where January 1 of
year 1 has ordinal 1. ValueError is raised unless
1 <=
ordinal <= date.max.toordinal(). For any date d, date.fromordinal(d.toordinal())
== d.
Class attributes:
- min
- The earliest representable date,
date(MINYEAR, 1, 1).
- max
- The latest representable date,
date(MAXYEAR, 12, 31).
- resolution
- The smallest possible difference between non-equal date objects,
timedelta(days=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.
Supported operations:
date2 = date1 + timedelta |
date2 is timedelta.days days removed
from date1. (1) |
|
date2 = date1 - timedelta |
Computes date2 such that date2 + timedelta
== date1. (2) |
|
timedelta = date1 -
date2 |
(3) |
|
date1<date2 |
date1 is considered less than date2 when date1
precedes date2 in time. (4) |
|
Notes:
- (1)
- date2 is moved forward in time if
timedelta.days
> 0, or backward if timedelta.days < 0.
Afterward date2 - date1 == timedelta.days.
timedelta.seconds and timedelta.microseconds
are ignored. OverflowError is raised if date2.year
would be smaller than MINYEAR or larger than MAXYEAR.
- (2)
- This isn't quite equivalent to date1 + (-timedelta), because -timedelta in
isolation can overflow in cases where date1 - timedelta does not.
timedelta.seconds
and timedelta.microseconds are ignored.
- (3)
- This is exact, and cannot overflow. timedelta.seconds and timedelta.microseconds
are 0, and date2 + timedelta == date1 after.
- (4)
- In other words,
date1 < date2 if and only if date1.toordinal()
< date2.toordinal(). In order to stop comparison from falling
back to the default scheme of comparing object addresses, date comparison normally
raises TypeError if the other comparand isn't also a date object. However, NotImplemented is returned
instead if the other comparand has a timetuple attribute.
This hook gives other kinds of date objects a chance at implementing mixed-type
comparison. If not, when a date object is compared to an
object of a different type, TypeError is raised unless
the comparison is == or !=. The latter cases return False or True, respectively.
Dates can be used as dictionary keys. In Boolean contexts, all date
objects are considered to be true.
Instance methods:
-
| replace( |
year, month, day) |
- Return a date with the same value, except for those members given new values by
whichever keyword arguments are specified. For example, if
d == date(2002,
12, 31), then d.replace(day=26) == date(2000, 12, 26).
-
- Return a time.struct_time such as returned by time.localtime(). The hours, minutes and seconds are 0, and
the DST flag is -1.
d.timetuple() is equivalent to time.struct_time((d.year,
d.month, d.day, 0, 0, 0, d.weekday(), d.toordinal()
- date(d.year, 1, 1).toordinal() + 1, -1))
-
- Return the proleptic Gregorian ordinal of the date, where January 1 of year 1
has ordinal 1. For any date object d,
date.fromordinal(d.toordinal())
== d.
-
- Return the day of the week as an integer, where Monday is 0 and Sunday is 6. For
example,
date(2002, 12, 4).weekday() == 2, a Wednesday. See also isoweekday().
-
- Return the day of the week as an integer, where Monday is 1 and Sunday is 7. For
example,
date(2002, 12, 4).isoweekday() == 3, a Wednesday. See also weekday(), isocalendar().
-
- Return a 3-tuple, (ISO year, ISO week number, ISO weekday).
The ISO calendar is a widely used variant of the Gregorian calendar. See
http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm for a good explanation.
The ISO year consists of 52 or 53 full weeks, and where a week starts on a
Monday and ends on a Sunday. The first week of an ISO year is the first
(Gregorian) calendar week of a year containing a Thursday. This is called week
number 1, and the ISO year of that Thursday is the same as its Gregorian year.
For example, 2004 begins on a Thursday, so the first week of ISO year 2004
begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan 2004, so that date(2003,
12, 29).isocalendar() == (2004, 1, 1) and date(2004, 1, 4).isocalendar()
== (2004, 1, 7).
-
- Return a string representing the date in ISO 8601 format, 'YYYY-MM-DD'. For
example,
date(2002, 12, 4).isoformat() == '2002-12-04'.
-
- For a date d,
str(d) is equivalent to d.isoformat().
-
- 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 ctime() function (which
time.ctime() invokes, but which date.ctime()
does not invoke) conforms to the C standard.
-
- Return a string representing the date, controlled by an explicit format string.
Format codes referring to hours, minutes or seconds will see 0 values. See the
section on strftime() behavior.
|
