6.10.3 date Objects

##
6.10.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 <= MAXYEAR`
  - `1 <= month <= 12`
  - `1 <= 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:

`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 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()`.

`fromordinal`( | ordinal)

  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:

Operation | Result
--- | ---
`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(2002, 12, 26)`.

`timetuple`( | )

  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))`

`toordinal`( | )

  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`.

`weekday`( | )

  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()`.

`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()`.

`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)`.

`isoformat`( | )

  Return a string representing the date in ISO 8601 format, 'YYYY-MM-DD'. For example, `date(2002, 12, 4).isoformat() == '2002-12-04'`.

`__str__`( | )

  For a date d, `str(d)` is equivalent to `d.isoformat()`.

`ctime`( | )

  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.

`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. See the section on `strftime()` behavior.