sam-t2/devtools/amd64/html/python/lib/datetime-date.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="datetime-datetime.html" />
<link rel="prev" href="datetime-timedelta.html" />
<link rel="parent" href="module-datetime.html" />
<link rel="next" href="datetime-datetime.html" />
<meta name='aesop' content='information' />
<title>6.10.3 date Objects </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="6.10.2 timedelta Objects"
  href="datetime-timedelta.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="6.10 datetime  "
  href="module-datetime.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="6.10.4 datetime Objects"
  href="datetime-datetime.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="datetime-timedelta.html">6.10.2 timedelta Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-datetime.html">6.10 datetime  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="datetime-datetime.html">6.10.4 datetime Objects</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION0081030000000000000000"></A><A NAME="datetime-date"></A>
<BR>
6.10.3 <tt class="class">date</tt> Objects
</H2>

<P>
A <tt class="class">date</tt> 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
<em class="citetitle"
 >Calendrical Calculations</em>, 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.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-1867' xml:id='l2h-1867' class="class">date</tt></b>(</nobr></td>
  <td><var>year, month, day</var>)</td></tr></table></dt>
<dd>
  All arguments are required.  Arguments may be ints or longs, in the
  following ranges:

<P>

<UL>
<LI><code>MINYEAR &lt;= <var>year</var> &lt;= MAXYEAR</code>
</LI>
<LI><code>1 &lt;= <var>month</var> &lt;= 12</code>
</LI>
<LI><code>1 &lt;= <var>day</var> &lt;= number of days in the given month and year</code>

</LI>
</UL>

<P>
If an argument outside those ranges is given, <tt class="exception">ValueError</tt>
  is raised.
</dl>

<P>
Other constructors, all class methods:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1868' xml:id='l2h-1868' class="method">today</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return the current local date.  This is equivalent to
  <code>date.fromtimestamp(time.time())</code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1869' xml:id='l2h-1869' class="method">fromtimestamp</tt></b>(</nobr></td>
  <td><var>timestamp</var>)</td></tr></table></dt>
<dd>
  Return the local date corresponding to the POSIX timestamp, such
  as is returned by <tt class="function">time.time()</tt>.  This may raise
  <tt class="exception">ValueError</tt>, if the timestamp is out of the range of
  values supported by the platform C <tt class="cfunction">localtime()</tt>
  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
  <tt class="method">fromtimestamp()</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1870' xml:id='l2h-1870' class="method">fromordinal</tt></b>(</nobr></td>
  <td><var>ordinal</var>)</td></tr></table></dt>
<dd>
  Return the date corresponding to the proleptic Gregorian ordinal,
  where January 1 of year 1 has ordinal 1.  <tt class="exception">ValueError</tt> is
  raised unless <code>1 &lt;= <var>ordinal</var> &lt;= date.max.toordinal()</code>.
  For any date <var>d</var>, <code>date.fromordinal(<var>d</var>.toordinal()) ==
  <var>d</var></code>.
</dl>

<P>
Class attributes:

<P>
<dl><dt><b><tt id='l2h-1871' xml:id='l2h-1871' class="member">min</tt></b></dt>
<dd>
  The earliest representable date, <code>date(MINYEAR, 1, 1)</code>.
</dl>

<P>
<dl><dt><b><tt id='l2h-1872' xml:id='l2h-1872' class="member">max</tt></b></dt>
<dd>
  The latest representable date, <code>date(MAXYEAR, 12, 31)</code>.
</dl>

<P>
<dl><dt><b><tt id='l2h-1873' xml:id='l2h-1873' class="member">resolution</tt></b></dt>
<dd>
  The smallest possible difference between non-equal date
  objects, <code>timedelta(days=1)</code>.
</dl>

<P>
Instance attributes (read-only):

<P>
<dl><dt><b><tt id='l2h-1874' xml:id='l2h-1874' class="member">year</tt></b></dt>
<dd>
  Between <tt class="constant">MINYEAR</tt> and <tt class="constant">MAXYEAR</tt> inclusive.
</dl>

<P>
<dl><dt><b><tt id='l2h-1875' xml:id='l2h-1875' class="member">month</tt></b></dt>
<dd>
  Between 1 and 12 inclusive.
</dl>

<P>
<dl><dt><b><tt id='l2h-1876' xml:id='l2h-1876' class="member">day</tt></b></dt>
<dd>
  Between 1 and the number of days in the given month of the given
  year.
</dl>

<P>
Supported operations:

<P>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="center">Operation</th>
      <th class="left"  >Result</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="center" valign="baseline"><code><var>date2</var> = <var>date1</var> + <var>timedelta</var></code></td>
        <td class="left"  ><var>date2</var> is <code><var>timedelta</var>.days</code> days removed from
    <var>date1</var>.  (1)</td></tr><P>

    <tr><td class="center" valign="baseline"><code><var>date2</var> = <var>date1</var> - <var>timedelta</var></code></td>
        <td class="left"  >Computes <var>date2</var> such that <code><var>date2</var> + <var>timedelta</var>
   == <var>date1</var></code>. (2)</td></tr><P>

    <tr><td class="center" valign="baseline"><code><var>timedelta</var> = <var>date1</var> - <var>date2</var></code></td>
        <td class="left"  >(3)</td></tr><P>

    <tr><td class="center" valign="baseline"><code><var>date1</var> &lt; <var>date2</var></code></td>
        <td class="left"  ><var>date1</var> is considered less than <var>date2</var> when <var>date1</var>
   precedes <var>date2</var> in time. (4)</td></tr><P>

    </tbody>
</table></div>

<P>
Notes:
<DL>
<DT><STRONG>(1)</STRONG></DT>
<DD><var>date2</var> is moved forward in time if <code><var>timedelta</var>.days
    &gt; 0</code>, or backward if <code><var>timedelta</var>.days &lt; 0</code>.  Afterward
    <code><var>date2</var> - <var>date1</var> == <var>timedelta</var>.days</code>.
    <code><var>timedelta</var>.seconds</code> and
    <code><var>timedelta</var>.microseconds</code> are ignored.
    <tt class="exception">OverflowError</tt> is raised if <code><var>date2</var>.year</code>
    would be smaller than <tt class="constant">MINYEAR</tt> or larger than
    <tt class="constant">MAXYEAR</tt>.

<P>
</DD>
<DT><STRONG>(2)</STRONG></DT>
<DD>This isn't quite equivalent to date1 +
   (-timedelta), because -timedelta in isolation can overflow in cases
   where date1 - timedelta does not.  <code><var>timedelta</var>.seconds</code>
   and <code><var>timedelta</var>.microseconds</code> are ignored.

<P>
</DD>
<DT><STRONG>(3)</STRONG></DT>
<DD>This is exact, and cannot overflow.  timedelta.seconds and
    timedelta.microseconds are 0, and date2 + timedelta == date1
    after.

<P>
</DD>
<DT><STRONG>(4)</STRONG></DT>
<DD>In other words, <code>date1 &lt; date2</code>
   if and only if <code><var>date1</var>.toordinal() &lt;
   <var>date2</var>.toordinal()</code>.
In order to stop comparison from falling back to the default
scheme of comparing object addresses, date comparison
normally raises <tt class="exception">TypeError</tt> if the other comparand
isn't also a <tt class="class">date</tt> object.  However, <code>NotImplemented</code>
is returned instead if the other comparand has a
<tt class="method">timetuple</tt> attribute.  This hook gives other kinds of
date objects a chance at implementing mixed-type comparison.
If not, when a <tt class="class">date</tt> object is
compared to an object of a different type, <tt class="exception">TypeError</tt> is
raised unless the comparison is <code>==</code> or <code>!=</code>.  The latter
cases return <tt class="constant">False</tt> or <tt class="constant">True</tt>, respectively.

<P>
</DD>
</DL>

<P>
Dates can be used as dictionary keys. In Boolean contexts, all
<tt class="class">date</tt> objects are considered to be true.

<P>
Instance methods:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1877' xml:id='l2h-1877' class="method">replace</tt></b>(</nobr></td>
  <td><var>year, month, day</var>)</td></tr></table></dt>
<dd>
  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)</code>, then
  <code>d.replace(day=26) == date(2002, 12, 26)</code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1878' xml:id='l2h-1878' class="method">timetuple</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return a <tt class="class">time.struct_time</tt> such as returned by
  <tt class="function">time.localtime()</tt>.  The hours, minutes and seconds are
  0, and the DST flag is -1.
  <code><var>d</var>.timetuple()</code> is equivalent to
      <code>time.struct_time((<var>d</var>.year, <var>d</var>.month, <var>d</var>.day,
             0, 0, 0,
             <var>d</var>.weekday(),
             <var>d</var>.toordinal() - date(<var>d</var>.year, 1, 1).toordinal() + 1,
            -1))</code>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1879' xml:id='l2h-1879' class="method">toordinal</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return the proleptic Gregorian ordinal of the date, where January 1
  of year 1 has ordinal 1.  For any <tt class="class">date</tt> object <var>d</var>,
  <code>date.fromordinal(<var>d</var>.toordinal()) == <var>d</var></code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1880' xml:id='l2h-1880' class="method">weekday</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return the day of the week as an integer, where Monday is 0 and
  Sunday is 6.  For example, <code>date(2002, 12, 4).weekday() == 2</code>, a
  Wednesday.
  See also <tt class="method">isoweekday()</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1881' xml:id='l2h-1881' class="method">isoweekday</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return the day of the week as an integer, where Monday is 1 and
  Sunday is 7.  For example, <code>date(2002, 12, 4).isoweekday() == 3</code>, a
  Wednesday.
  See also <tt class="method">weekday()</tt>, <tt class="method">isocalendar()</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1882' xml:id='l2h-1882' class="method">isocalendar</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return a 3-tuple, (ISO year, ISO week number, ISO weekday).

<P>
The ISO calendar is a widely used variant of the Gregorian calendar.
  See <a class="url" href="http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm">http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm</a>  for a good explanation.

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

<P>
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
  <code>date(2003, 12, 29).isocalendar() == (2004, 1, 1)</code>
  and
  <code>date(2004, 1, 4).isocalendar() == (2004, 1, 7)</code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1883' xml:id='l2h-1883' class="method">isoformat</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return a string representing the date in ISO 8601 format,
  'YYYY-MM-DD'.  For example,
  <code>date(2002, 12, 4).isoformat() == '2002-12-04'</code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1884' xml:id='l2h-1884' class="method">__str__</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  For a date <var>d</var>, <code>str(<var>d</var>)</code> is equivalent to
  <code><var>d</var>.isoformat()</code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1885' xml:id='l2h-1885' class="method">ctime</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return a string representing the date, for example
  date(2002, 12, 4).ctime() == 'Wed Dec  4 00:00:00 2002'.
  <code><var>d</var>.ctime()</code> is equivalent to
  <code>time.ctime(time.mktime(<var>d</var>.timetuple()))</code>
  on platforms where the native C <tt class="cfunction">ctime()</tt> function
  (which <tt class="function">time.ctime()</tt> invokes, but which
  <tt class="method">date.ctime()</tt> does not invoke) conforms to the C standard.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1886' xml:id='l2h-1886' class="method">strftime</tt></b>(</nobr></td>
  <td><var>format</var>)</td></tr></table></dt>
<dd>
  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 <tt class="method">strftime()</tt> behavior.
</dl>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="6.10.2 timedelta Objects"
  href="datetime-timedelta.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="6.10 datetime  "
  href="module-datetime.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="6.10.4 datetime Objects"
  href="datetime-datetime.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="datetime-timedelta.html">6.10.2 timedelta Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-datetime.html">6.10 datetime  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="datetime-datetime.html">6.10.4 datetime Objects</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>