:mod:`datetime` --- Basic date and time types

=============================================

.. module:: datetime

   :synopsis: Basic date and time types.

.. moduleauthor:: Tim Peters <tim@zope.com>

.. sectionauthor:: Tim Peters <tim@zope.com>

.. sectionauthor:: A.M. Kuchling <amk@amk.ca>

.. XXX what order should the types be discussed in?

.. versionadded:: 2.3

The :mod:`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 member extraction for output

formatting and manipulation. For related

functionality, see also the :mod:`time` and :mod:`calendar` modules.

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

saving 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 metres,

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, :class:`datetime` and :class:`time` objects

have an optional time zone information member, :attr:`tzinfo`, that can contain

an instance of a subclass of the abstract :class:`tzinfo` class.  These

:class:`tzinfo` objects capture information about the offset from UTC time, the

time zone name, and whether Daylight Saving Time is in effect.  Note that no

concrete :class:`tzinfo` classes are supplied by the :mod:`datetime` module.

Supporting timezones at whatever level of detail is required is up to the

application.  The rules for time adjustment across the world are more political

than rational, and there is no standard suitable for every application.

The :mod:`datetime` module exports the following constants:

.. data:: MINYEAR

   The smallest year number allowed in a :class:`date` or :class:`datetime` object.

   :const:`MINYEAR` is ``1``.

.. data:: MAXYEAR

   The largest year number allowed in a :class:`date` or :class:`datetime` object.

   :const:`MAXYEAR` is ``9999``.

.. seealso::

   Module :mod:`calendar`

      General calendar related functions.

   Module :mod:`time`

      Time access and conversions.

Available Types

---------------

.. class:: date

   An idealized naive date, assuming the current Gregorian calendar always was, and

   always will be, in effect. Attributes: :attr:`year`, :attr:`month`, and

   :attr:`day`.

.. class:: time

   An idealized time, independent of any particular day, assuming that every day

   has exactly 24\*60\*60 seconds (there is no notion of "leap seconds" here).

   Attributes: :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,

   and :attr:`tzinfo`.

.. class:: datetime

   A combination of a date and a time. Attributes: :attr:`year`, :attr:`month`,

   :attr:`day`, :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,

   and :attr:`tzinfo`.

.. class:: timedelta

   A duration expressing the difference between two :class:`date`, :class:`time`,

   or :class:`datetime` instances to microsecond resolution.

.. class:: tzinfo

   An abstract base class for time zone information objects.  These are used by the

   :class:`datetime` and :class:`time` classes to provide a customizable notion of

   time adjustment (for example, to account for time zone and/or daylight saving

   time).

Objects of these types are immutable.

Objects of the :class:`date` type are always naive.

An object *d* of type :class:`time` or :class:`datetime` 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 :class:`timedelta`

objects.

Subclass relationships::

   object

       timedelta

       tzinfo

       time

       date

           datetime

.. _datetime-timedelta:

:class:`timedelta` Objects

--------------------------

A :class:`timedelta` object represents a duration, the difference between two

dates or times.

.. class:: timedelta([days[, seconds[, microseconds[, milliseconds[, minutes[, hours[, weeks]]]]]]])

   All arguments are optional and default to ``0``.  Arguments may be ints, longs,

   or floats, and may be positive or negative.

   Only *days*, *seconds* and *microseconds* are stored internally.  Arguments are

   converted to those units:

   * A millisecond is converted to 1000 microseconds.

   * A minute is converted to 60 seconds.

   * An hour is converted to 3600 seconds.

   * A week is converted to 7 days.

   and days, seconds and microseconds are then normalized so that the

   representation is unique, with

   * ``0 <= microseconds < 1000000``

   * ``0 <= seconds < 3600*24`` (the number of seconds in one day)

   * ``-999999999 <= days <= 999999999``

   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 float, the conversion and

   normalization processes are exact (no information is lost).

   If the normalized value of days lies outside the indicated range,

   :exc:`OverflowError` is raised.

   Note that normalization of negative values may be surprising at first. For

   example,

      >>> from datetime import timedelta

      >>> d = timedelta(microseconds=-1)

      >>> (d.days, d.seconds, d.microseconds)

      (-1, 86399, 999999)

Class attributes are:

.. attribute:: timedelta.min

   The most negative :class:`timedelta` object, ``timedelta(-999999999)``.

.. attribute:: timedelta.max

   The most positive :class:`timedelta` object, ``timedelta(days=999999999,

   hours=23, minutes=59, seconds=59, microseconds=999999)``.

.. attribute:: timedelta.resolution

   The smallest possible difference between non-equal :class:`timedelta` objects,

   ``timedelta(microseconds=1)``.

Note that, because of normalization, ``timedelta.max`` > ``-timedelta.min``.

``-timedelta.max`` is not representable as a :class:`timedelta` object.

Instance attributes (read-only):

+------------------+--------------------------------------------+

| Attribute        | Value                                      |

+==================+============================================+

| ``days``         | Between -999999999 and 999999999 inclusive |

+------------------+--------------------------------------------+

| ``seconds``      | Between 0 and 86399 inclusive              |

+------------------+--------------------------------------------+

| ``microseconds`` | Between 0 and 999999 inclusive             |

+------------------+--------------------------------------------+

Supported operations:

.. XXX this table is too wide!

+--------------------------------+-----------------------------------------------+

| Operation                      | Result                                        |

+================================+===============================================+

| ``t1 = t2 + t3``               | Sum of *t2* and *t3*. Afterwards *t1*-*t2* == |

|                                | *t3* and *t1*-*t3* == *t2* are true. (1)      |

+--------------------------------+-----------------------------------------------+

| ``t1 = t2 - t3``               | Difference of *t2* and *t3*. Afterwards *t1*  |

|                                | == *t2* - *t3* and *t2* == *t1* + *t3* are    |

|                                | true. (1)                                     |

+--------------------------------+-----------------------------------------------+

| ``t1 = t2 * i or t1 = i * t2`` | Delta multiplied by an integer or long.       |

|                                | Afterwards *t1* // i == *t2* is true,         |

|                                | provided ``i != 0``.                          |

+--------------------------------+-----------------------------------------------+

|                                | In general, *t1* \* i == *t1* \* (i-1) + *t1* |

|                                | is true. (1)                                  |

+--------------------------------+-----------------------------------------------+

| ``t1 = t2 // i``               | The floor is computed and the remainder (if   |

|                                | any) is thrown away. (3)                      |

+--------------------------------+-----------------------------------------------+

| ``+t1``                        | Returns a :class:`timedelta` object with the  |

|                                | same value. (2)                               |

+--------------------------------+-----------------------------------------------+

| ``-t1``                        | equivalent to :class:`timedelta`\             |

|                                | (-*t1.days*, -*t1.seconds*,                   |

|                                | -*t1.microseconds*), and to *t1*\* -1. (1)(4) |

+--------------------------------+-----------------------------------------------+

| ``abs(t)``                     | equivalent to +*t* when ``t.days >= 0``, and  |

|                                | to -*t* when ``t.days < 0``. (2)              |

+--------------------------------+-----------------------------------------------+

Notes:

(1)

   This is exact, but may overflow.

(2)

   This is exact, and cannot overflow.

(3)

   Division by 0 raises :exc:`ZeroDivisionError`.

(4)

   -*timedelta.max* is not representable as a :class:`timedelta` object.

In addition to the operations listed above :class:`timedelta` objects support

certain additions and subtractions with :class:`date` and :class:`datetime`

objects (see below).

Comparisons of :class:`timedelta` objects are supported with the

:class:`timedelta` object representing the smaller duration considered to be the

smaller timedelta. In order to stop mixed-type comparisons from falling back to

the default comparison by object address, when a :class:`timedelta` object is

compared to an object of a different type, :exc:`TypeError` is raised unless the

comparison is ``==`` or ``!=``.  The latter cases return :const:`False` or

:const:`True`, respectively.

:class:`timedelta` objects are :term:`hashable` (usable as dictionary keys), support

efficient pickling, and in Boolean contexts, a :class:`timedelta` object is

considered to be true if and only if it isn't equal to ``timedelta(0)``.

Example usage:

    >>> from datetime import timedelta

    >>> year = timedelta(days=365)

    >>> another_year = timedelta(weeks=40, days=84, hours=23, 

    ...                          minutes=50, seconds=600)  # adds up to 365 days

    >>> year == another_year

    True

    >>> ten_years = 10 * year

    >>> ten_years, ten_years.days // 365

    (datetime.timedelta(3650), 10)

    >>> nine_years = ten_years - year

    >>> nine_years, nine_years.days // 365

    (datetime.timedelta(3285), 9)

    >>> three_years = nine_years // 3;

    >>> three_years, three_years.days // 365

    (datetime.timedelta(1095), 3)

    >>> abs(three_years - ten_years) == 2 * three_years + year

    True

.. _datetime-date:

:class:`date` Objects

---------------------

A :class:`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, :exc:`ValueError` is raised.

Other constructors, all class methods:

.. method:: date.today()

   Return the current local date.  This is equivalent to

   ``date.fromtimestamp(time.time())``.

.. method:: date.fromtimestamp(timestamp)

   Return the local date corresponding to the POSIX timestamp, such as is returned

   by :func:`time.time`.  This may raise :exc:`ValueError`, if the timestamp is out

   of the range of values supported by the platform C :cfunc:`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 :meth:`fromtimestamp`.

.. method:: date.fromordinal(ordinal)

   Return the date corresponding to the proleptic Gregorian ordinal, where January

   1 of year 1 has ordinal 1.  :exc:`ValueError` is raised unless ``1 <= ordinal <=

   date.max.toordinal()``. For any date *d*, ``date.fromordinal(d.toordinal()) ==

   d``.

Class attributes:

.. attribute:: date.min

   The earliest representable date, ``date(MINYEAR, 1, 1)``.

.. attribute:: date.max

   The latest representable date, ``date(MAXYEAR, 12, 31)``.

.. attribute:: date.resolution

   The smallest possible difference between non-equal date objects,

   ``timedelta(days=1)``.

Instance attributes (read-only):

.. attribute:: date.year

   Between :const:`MINYEAR` and :const:`MAXYEAR` inclusive.

.. attribute:: date.month

   Between 1 and 12 inclusive.

.. attribute:: date.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.

   :exc:`OverflowError` is raised if ``date2.year`` would be smaller than

   :const:`MINYEAR` or larger than :const:`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

   :exc:`TypeError` if the other comparand isn't also a :class:`date` object.

   However, ``NotImplemented`` is returned instead if the other comparand has a

   :meth:`timetuple` attribute.  This hook gives other kinds of date objects a

   chance at implementing mixed-type comparison. If not, when a :class:`date`

   object is compared to an object of a different type, :exc:`TypeError` is raised

   unless the comparison is ``==`` or ``!=``.  The latter cases return

   :const:`False` or :const:`True`, respectively.

Dates can be used as dictionary keys. In Boolean contexts, all :class:`date`

objects are considered to be true.

Instance methods:

.. method:: date.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)``.

.. method:: date.timetuple()

   Return a :class:`time.struct_time` such as returned by :func:`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))``

.. method:: date.toordinal()

   Return the proleptic Gregorian ordinal of the date, where January 1 of year 1

   has ordinal 1.  For any :class:`date` object *d*,

   ``date.fromordinal(d.toordinal()) == d``.

.. method:: date.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

   :meth:`isoweekday`.

.. method:: date.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

   :meth:`weekday`, :meth:`isocalendar`.

.. method:: date.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)``.

.. method:: date.isoformat()

   Return a string representing the date in ISO 8601 format, 'YYYY-MM-DD'.  For

   example, ``date(2002, 12, 4).isoformat() == '2002-12-04'``.

.. method:: date.__str__()

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

.. method:: date.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

   :cfunc:`ctime` function (which :func:`time.ctime` invokes, but which

   :meth:`date.ctime` does not invoke) conforms to the C standard.

.. method:: date.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

   section :ref:`strftime-behavior`.

Example of counting days to an event::

    >>> import time

    >>> from datetime import date

    >>> today = date.today()

    >>> today

    datetime.date(2007, 12, 5)

    >>> today == date.fromtimestamp(time.time())

    True

    >>> my_birthday = date(today.year, 6, 24)

    >>> if my_birthday < today:

    ...     my_birthday = my_birthday.replace(year=today.year + 1) 

    >>> my_birthday

    datetime.date(2008, 6, 24)

    >>> time_to_birthday = abs(my_birthday - today) 

    >>> time_to_birthday.days

    202

Example of working with :class:`date`: