datetime.rst 75.2 KB
Newer Older
1 2 3 4 5 6 7 8 9
: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>

10
.. XXX what order should the types be discussed in?
11 12 13

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
14
focus of the implementation is on efficient attribute extraction for output
15 16
formatting and manipulation. For related functionality, see also the
:mod:`time` and :mod:`calendar` modules.
17

18 19 20 21 22 23 24 25 26 27
There are two kinds of date and time objects: "naive" and "aware".

An aware object has sufficient knowledge of applicable algorithmic and
political time adjustments, such as time zone and daylight saving time
information, to locate itself relative to other aware objects.  An aware object
is used to represent a specific moment in time that is not open to
interpretation [#]_.

A naive object does not contain enough information to unambiguously locate
itself relative to other date/time objects.  Whether a naive object represents
28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
Coordinated Universal Time (UTC), local time, or time in some other timezone is
purely up to the program, just like it is up to the program whether a
particular number represents metres, miles, or mass.  Naive objects are easy to
understand and to work with, at the cost of ignoring some aspects of reality.

For applications requiring aware objects, :class:`.datetime` and :class:`.time`
objects have an optional time zone information attribute, :attr:`tzinfo`, that
can be set to 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 only one concrete :class:`tzinfo` class, the :class:`timezone` class, is
supplied by the :mod:`datetime` module.  The :class:`timezone` class can
represent simple timezones with fixed offset from UTC, such as UTC itself or
North American EST and EDT timezones.  Supporting timezones at deeper levels of
detail is up to the application.  The rules for time adjustment across the
43 44
world are more political than rational, change frequently, and there is no
standard suitable for every application aside from UTC.
45 46 47 48 49

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

.. data:: MINYEAR

50
   The smallest year number allowed in a :class:`date` or :class:`.datetime` object.
51 52 53 54 55
   :const:`MINYEAR` is ``1``.


.. data:: MAXYEAR

56
   The largest year number allowed in a :class:`date` or :class:`.datetime` object.
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
   :const:`MAXYEAR` is ``9999``.


.. seealso::

   Module :mod:`calendar`
      General calendar related functions.

   Module :mod:`time`
      Time access and conversions.


Available Types
---------------

.. class:: date
Benjamin Peterson's avatar
Benjamin Peterson committed
73
   :noindex:
74 75 76 77 78 79 80

   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
Benjamin Peterson's avatar
Benjamin Peterson committed
81
   :noindex:
82 83 84 85 86 87 88 89

   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
Benjamin Peterson's avatar
Benjamin Peterson committed
90
   :noindex:
91 92 93 94 95 96 97

   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
Benjamin Peterson's avatar
Benjamin Peterson committed
98
   :noindex:
99

100 101
   A duration expressing the difference between two :class:`date`, :class:`.time`,
   or :class:`.datetime` instances to microsecond resolution.
102 103 104 105 106


.. class:: tzinfo

   An abstract base class for time zone information objects.  These are used by the
107
   :class:`.datetime` and :class:`.time` classes to provide a customizable notion of
108 109 110
   time adjustment (for example, to account for time zone and/or daylight saving
   time).

111 112 113 114 115 116 117 118
.. class:: timezone

   A class that implements the :class:`tzinfo` abstract base class as a
   fixed offset from the UTC.

   .. versionadded:: 3.2


119 120 121 122
Objects of these types are immutable.

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

123 124 125 126 127 128 129
An object of type :class:`.time` or :class:`.datetime` may be naive or aware.
A :class:`.datetime` object *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.  A :class:`.time` object *t* is aware
if ``t.tzinfo`` is not ``None`` and ``t.tzinfo.utcoffset(None)`` does not return
``None``.  Otherwise, *t* is naive.
130 131 132 133 134 135 136 137 138

The distinction between naive and aware doesn't apply to :class:`timedelta`
objects.

Subclass relationships::

   object
       timedelta
       tzinfo
139
           timezone
140 141 142 143 144 145 146 147 148 149 150 151 152
       time
       date
           datetime


.. _datetime-timedelta:

:class:`timedelta` Objects
--------------------------

A :class:`timedelta` object represents a duration, the difference between two
dates or times.

153
.. class:: timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)
154

155
   All arguments are optional and default to ``0``.  Arguments may be integers
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181
   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
Christian Heimes's avatar
Christian Heimes committed
182
   example,
183

184
      >>> from datetime import timedelta
185 186 187 188 189
      >>> d = timedelta(microseconds=-1)
      >>> (d.days, d.seconds, d.microseconds)
      (-1, 86399, 999999)


Benjamin Peterson's avatar
Benjamin Peterson committed
190
Class attributes are:
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224

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

225
.. XXX this table is too wide!
226 227 228 229 230 231 232 233 234 235 236

+--------------------------------+-----------------------------------------------+
| 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)                                     |
+--------------------------------+-----------------------------------------------+
237
| ``t1 = t2 * i or t1 = i * t2`` | Delta multiplied by an integer.               |
238 239 240 241 242 243
|                                | Afterwards *t1* // i == *t2* is true,         |
|                                | provided ``i != 0``.                          |
+--------------------------------+-----------------------------------------------+
|                                | In general, *t1* \* i == *t1* \* (i-1) + *t1* |
|                                | is true. (1)                                  |
+--------------------------------+-----------------------------------------------+
244 245 246 247
| ``t1 = t2 * f or t1 = f * t2`` | Delta multiplied by a float. The result is    |
|                                | rounded to the nearest multiple of            |
|                                | timedelta.resolution using round-half-to-even.|
+--------------------------------+-----------------------------------------------+
248 249 250
| ``f = t2 / t3``                | Division (3) of *t2* by *t3*.  Returns a      |
|                                | :class:`float` object.                        |
+--------------------------------+-----------------------------------------------+
251 252 253 254
| ``t1 = t2 / f or t1 = t2 / i`` | Delta divided by a float or an int. The result|
|                                | is rounded to the nearest multiple of         |
|                                | timedelta.resolution using round-half-to-even.|
+--------------------------------+-----------------------------------------------+
255 256
| ``t1 = t2 // i`` or            | The floor is computed and the remainder (if   |
| ``t1 = t2 // t3``              | any) is thrown away.  In the second case, an  |
257
|                                | integer is returned. (3)                      |
258 259 260 261 262 263 264 265
+--------------------------------+-----------------------------------------------+
| ``t1 = t2 % t3``               | The remainder is computed as a                |
|                                | :class:`timedelta` object. (3)                |
+--------------------------------+-----------------------------------------------+
| ``q, r = divmod(t1, t2)``      | Computes the quotient and the remainder:      |
|                                | ``q = t1 // t2`` (3) and ``r = t1 % t2``.     |
|                                | q is an integer and r is a :class:`timedelta` |
|                                | object.                                       |
266 267 268 269 270 271 272 273
+--------------------------------+-----------------------------------------------+
| ``+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) |
+--------------------------------+-----------------------------------------------+
Georg Brandl's avatar
Georg Brandl committed
274
| ``abs(t)``                     | equivalent to +\ *t* when ``t.days >= 0``, and|
275 276
|                                | to -*t* when ``t.days < 0``. (2)              |
+--------------------------------+-----------------------------------------------+
277 278 279 280 281 282 283 284
| ``str(t)``                     | Returns a string in the form                  |
|                                | ``[D day[s], ][H]H:MM:SS[.UUUUUU]``, where D  |
|                                | is negative for negative ``t``. (5)           |
+--------------------------------+-----------------------------------------------+
| ``repr(t)``                    | Returns a string in the form                  |
|                                | ``datetime.timedelta(D[, S[, U]])``, where D  |
|                                | is negative for negative ``t``. (5)           |
+--------------------------------+-----------------------------------------------+
285 286 287 288 289 290 291 292 293 294 295 296 297 298 299

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.

300 301 302 303 304 305 306 307 308 309
(5)
  String representations of :class:`timedelta` objects are normalized
  similarly to their internal representation.  This leads to somewhat
  unusual results for negative timedeltas.  For example:

  >>> timedelta(hours=-5)
  datetime.timedelta(-1, 68400)
  >>> print(_)
  -1 day, 19:00:00

310
In addition to the operations listed above :class:`timedelta` objects support
311
certain additions and subtractions with :class:`date` and :class:`.datetime`
312
objects (see below).
313

314 315 316 317 318
.. versionchanged:: 3.2
   Floor division and true division of a :class:`timedelta` object by another
   :class:`timedelta` object are now supported, as are remainder operations and
   the :func:`divmod` function.  True division and multiplication of a
   :class:`timedelta` object by a :class:`float` object are now supported.
319

320 321 322 323 324 325 326 327 328

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.

329
:class:`timedelta` objects are :term:`hashable` (usable as dictionary keys), support
330 331 332
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)``.

333 334 335 336 337
Instance methods:

.. method:: timedelta.total_seconds()

   Return the total number of seconds contained in the duration. Equivalent to
338 339 340 341
   ``td / timedelta(seconds=1)``.

   Note that for very large time intervals (greater than 270 years on
   most platforms) this method will lose microsecond accuracy.
342 343 344 345

   .. versionadded:: 3.2


Christian Heimes's avatar
Christian Heimes committed
346
Example usage:
347

348 349
    >>> from datetime import timedelta
    >>> year = timedelta(days=365)
350
    >>> another_year = timedelta(weeks=40, days=84, hours=23,
351
    ...                          minutes=50, seconds=600)  # adds up to 365 days
352 353
    >>> year.total_seconds()
    31536000.0
354 355 356 357 358 359 360 361 362 363 364 365 366 367
    >>> 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

368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385

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

386
   All arguments are required.  Arguments may be integers, in the following
387 388 389 390 391 392 393 394 395
   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.


Benjamin Peterson's avatar
Benjamin Peterson committed
396
Other constructors, all class methods:
397

Benjamin Peterson's avatar
Benjamin Peterson committed
398
.. classmethod:: date.today()
399 400 401 402 403

   Return the current local date.  This is equivalent to
   ``date.fromtimestamp(time.time())``.


Benjamin Peterson's avatar
Benjamin Peterson committed
404
.. classmethod:: date.fromtimestamp(timestamp)
405 406

   Return the local date corresponding to the POSIX timestamp, such as is returned
407
   by :func:`time.time`.  This may raise :exc:`OverflowError`, if the timestamp is out
408 409
   of the range of values supported by the platform C :c:func:`localtime` function,
   and :exc:`OSError` on :c:func:`localtime` failure.
410 411 412 413
   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`.

414 415 416
   .. versionchanged:: 3.3
      Raise :exc:`OverflowError` instead of :exc:`ValueError` if the timestamp
      is out of the range of values supported by the platform C
417 418
      :c:func:`localtime` function. Raise :exc:`OSError` instead of
      :exc:`ValueError` on :c:func:`localtime` failure.
419

420

Benjamin Peterson's avatar
Benjamin Peterson committed
421
.. classmethod:: date.fromordinal(ordinal)
422 423 424 425 426 427 428

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


Benjamin Peterson's avatar
Benjamin Peterson committed
429
Class attributes:
430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446

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


Benjamin Peterson's avatar
Benjamin Peterson committed
447
Instance attributes (read-only):
448 449 450 451 452 453 454 455 456 457 458 459 460 461 462

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

Benjamin Peterson's avatar
Benjamin Peterson committed
463

464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517
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)

518 519 520
   Return a date with the same value, except for those parameters 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)``.
521 522 523 524 525 526 527


.. 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,
528 529 530
   d.weekday(), yday, -1))``, where ``yday = d.toordinal() - date(d.year, 1,
   1).toordinal() + 1`` is the day number within the current year starting with
   ``1`` for January 1st.
531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558


.. 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
559 560
   http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm for a good
   explanation.
561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588

   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
589
   :c:func:`ctime` function (which :func:`time.ctime` invokes, but which
590 591 592 593 594 595 596
   :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
Benjamin Peterson's avatar
Benjamin Peterson committed
597 598
   section :ref:`strftime-strptime-behavior`.

599

600 601 602 603 604 605 606 607 608 609 610
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:
611
    ...     my_birthday = my_birthday.replace(year=today.year + 1)
612 613
    >>> my_birthday
    datetime.date(2008, 6, 24)
614
    >>> time_to_birthday = abs(my_birthday - today)
615 616 617
    >>> time_to_birthday.days
    202

Christian Heimes's avatar
Christian Heimes committed
618 619 620
Example of working with :class:`date`:

.. doctest::
621 622 623 624 625 626

    >>> from datetime import date
    >>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
    >>> d
    datetime.date(2002, 3, 11)
    >>> t = d.timetuple()
Christian Heimes's avatar
Christian Heimes committed
627
    >>> for i in t:     # doctest: +SKIP
628
    ...     print(i)
629 630 631 632 633 634 635 636 637 638
    2002                # year
    3                   # month
    11                  # day
    0
    0
    0
    0                   # weekday (0 = Monday)
    70                  # 70th day in the year
    -1
    >>> ic = d.isocalendar()
Christian Heimes's avatar
Christian Heimes committed
639
    >>> for i in ic:    # doctest: +SKIP
640
    ...     print(i)
641 642 643 644 645 646 647 648 649 650
    2002                # ISO year
    11                  # ISO week number
    1                   # ISO day number ( 1 = Monday )
    >>> d.isoformat()
    '2002-03-11'
    >>> d.strftime("%d/%m/%y")
    '11/03/02'
    >>> d.strftime("%A %d. %B %Y")
    'Monday 11. March 2002'

651 652 653 654 655 656

.. _datetime-datetime:

:class:`datetime` Objects
-------------------------

657 658 659 660
A :class:`.datetime` object is a single object containing all the information
from a :class:`date` object and a :class:`.time` object.  Like a :class:`date`
object, :class:`.datetime` assumes the current Gregorian calendar extended in
both directions; like a time object, :class:`.datetime` assumes there are exactly
661 662 663 664
3600\*24 seconds in every day.

Constructor:

665
.. class:: datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None)
666 667

   The year, month and day arguments are required.  *tzinfo* may be ``None``, or an
668 669
   instance of a :class:`tzinfo` subclass.  The remaining arguments may be integers,
   in the following ranges:
670 671 672 673 674 675 676 677 678 679 680 681 682

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

Other constructors, all class methods:

Benjamin Peterson's avatar
Benjamin Peterson committed
683
.. classmethod:: datetime.today()
684 685 686 687 688 689

   Return the current local datetime, with :attr:`tzinfo` ``None``. This is
   equivalent to ``datetime.fromtimestamp(time.time())``. See also :meth:`now`,
   :meth:`fromtimestamp`.


Benjamin Peterson's avatar
Benjamin Peterson committed
690
.. classmethod:: datetime.now(tz=None)
691 692 693 694 695

   Return the current local date and time.  If optional argument *tz* is ``None``
   or not specified, this is like :meth:`today`, but, if possible, supplies more
   precision than can be gotten from going through a :func:`time.time` timestamp
   (for example, this may be possible on platforms supplying the C
696
   :c:func:`gettimeofday` function).
697 698 699 700 701 702 703

   Else *tz* must be an instance of a class :class:`tzinfo` subclass, and the
   current date and time are converted to *tz*'s time zone.  In this case the
   result is equivalent to ``tz.fromutc(datetime.utcnow().replace(tzinfo=tz))``.
   See also :meth:`today`, :meth:`utcnow`.


Benjamin Peterson's avatar
Benjamin Peterson committed
704
.. classmethod:: datetime.utcnow()
705 706 707

   Return the current UTC date and time, with :attr:`tzinfo` ``None``. This is like
   :meth:`now`, but returns the current UTC date and time, as a naive
708
   :class:`.datetime` object.  An aware current UTC datetime can be obtained by
709
   calling ``datetime.now(timezone.utc)``.  See also :meth:`now`.
710

Benjamin Peterson's avatar
Benjamin Peterson committed
711
.. classmethod:: datetime.fromtimestamp(timestamp, tz=None)
712 713 714 715

   Return the local date and time corresponding to the POSIX timestamp, such as is
   returned by :func:`time.time`. If optional argument *tz* is ``None`` or not
   specified, the timestamp is converted to the platform's local date and time, and
716
   the returned :class:`.datetime` object is naive.
717 718 719 720 721 722

   Else *tz* must be an instance of a class :class:`tzinfo` subclass, and the
   timestamp is converted to *tz*'s time zone.  In this case the result is
   equivalent to
   ``tz.fromutc(datetime.utcfromtimestamp(timestamp).replace(tzinfo=tz))``.

723
   :meth:`fromtimestamp` may raise :exc:`OverflowError`, if the timestamp is out of
724
   the range of values supported by the platform C :c:func:`localtime` or
725 726 727
   :c:func:`gmtime` functions, and :exc:`OSError` on :c:func:`localtime` or
   :c:func:`gmtime` failure.
   It's common for this to be restricted to years in
728 729 730
   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`,
   and then it's possible to have two timestamps differing by a second that yield
731
   identical :class:`.datetime` objects. See also :meth:`utcfromtimestamp`.
732

733 734 735
   .. versionchanged:: 3.3
      Raise :exc:`OverflowError` instead of :exc:`ValueError` if the timestamp
      is out of the range of values supported by the platform C
736 737 738
      :c:func:`localtime` or :c:func:`gmtime` functions. Raise :exc:`OSError`
      instead of :exc:`ValueError` on :c:func:`localtime` or :c:func:`gmtime`
      failure.
739

740

Benjamin Peterson's avatar
Benjamin Peterson committed
741
.. classmethod:: datetime.utcfromtimestamp(timestamp)
742

743
   Return the UTC :class:`.datetime` corresponding to the POSIX timestamp, with
744 745 746
   :attr:`tzinfo` ``None``. This may raise :exc:`OverflowError`, if the timestamp is
   out of the range of values supported by the platform C :c:func:`gmtime` function,
   and :exc:`OSError` on :c:func:`gmtime` failure.
747 748 749
   It's common for this to be restricted to years in 1970 through 2038. See also
   :meth:`fromtimestamp`.

750 751 752 753 754
   On the POSIX compliant platforms, ``utcfromtimestamp(timestamp)``
   is equivalent to the following expression::

     datetime(1970, 1, 1) + timedelta(seconds=timestamp)

755 756 757
   .. versionchanged:: 3.3
      Raise :exc:`OverflowError` instead of :exc:`ValueError` if the timestamp
      is out of the range of values supported by the platform C
758 759
      :c:func:`gmtime` function. Raise :exc:`OSError` instead of
      :exc:`ValueError` on :c:func:`gmtime` failure.
760

761

Benjamin Peterson's avatar
Benjamin Peterson committed
762
.. classmethod:: datetime.fromordinal(ordinal)
763

764
   Return the :class:`.datetime` corresponding to the proleptic Gregorian ordinal,
765 766 767 768 769
   where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1
   <= ordinal <= datetime.max.toordinal()``.  The hour, minute, second and
   microsecond of the result are all 0, and :attr:`tzinfo` is ``None``.


Benjamin Peterson's avatar
Benjamin Peterson committed
770
.. classmethod:: datetime.combine(date, time)
771

772
   Return a new :class:`.datetime` object whose date components are equal to the
773
   given :class:`date` object's, and whose time components and :attr:`tzinfo`
774 775
   attributes are equal to the given :class:`.time` object's. For any
   :class:`.datetime` object *d*,
776
   ``d == datetime.combine(d.date(), d.timetz())``.  If date is a
777
   :class:`.datetime` object, its time components and :attr:`tzinfo` attributes
778
   are ignored.
779 780


Benjamin Peterson's avatar
Benjamin Peterson committed
781
.. classmethod:: datetime.strptime(date_string, format)
782

783
   Return a :class:`.datetime` corresponding to *date_string*, parsed according to
784 785 786
   *format*.  This is equivalent to ``datetime(*(time.strptime(date_string,
   format)[0:6]))``. :exc:`ValueError` is raised if the date_string and format
   can't be parsed by :func:`time.strptime` or if it returns a value which isn't a
Benjamin Peterson's avatar
Benjamin Peterson committed
787
   time tuple. See section :ref:`strftime-strptime-behavior`.
788 789 790



Benjamin Peterson's avatar
Benjamin Peterson committed
791
Class attributes:
792 793 794

.. attribute:: datetime.min

795
   The earliest representable :class:`.datetime`, ``datetime(MINYEAR, 1, 1,
796 797 798 799 800
   tzinfo=None)``.


.. attribute:: datetime.max

801
   The latest representable :class:`.datetime`, ``datetime(MAXYEAR, 12, 31, 23, 59,
802 803 804 805 806
   59, 999999, tzinfo=None)``.


.. attribute:: datetime.resolution

807
   The smallest possible difference between non-equal :class:`.datetime` objects,
808 809 810
   ``timedelta(microseconds=1)``.


Benjamin Peterson's avatar
Benjamin Peterson committed
811
Instance attributes (read-only):
812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849

.. attribute:: datetime.year

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


.. attribute:: datetime.month

   Between 1 and 12 inclusive.


.. attribute:: datetime.day

   Between 1 and the number of days in the given month of the given year.


.. attribute:: datetime.hour

   In ``range(24)``.


.. attribute:: datetime.minute

   In ``range(60)``.


.. attribute:: datetime.second

   In ``range(60)``.


.. attribute:: datetime.microsecond

   In ``range(1000000)``.


.. attribute:: datetime.tzinfo

850
   The object passed as the *tzinfo* argument to the :class:`.datetime` constructor,
851 852
   or ``None`` if none was passed.

Benjamin Peterson's avatar
Benjamin Peterson committed
853

854 855
Supported operations:

856 857 858 859 860 861 862 863 864 865 866 867
+---------------------------------------+--------------------------------+
| Operation                             | Result                         |
+=======================================+================================+
| ``datetime2 = datetime1 + timedelta`` | \(1)                           |
+---------------------------------------+--------------------------------+
| ``datetime2 = datetime1 - timedelta`` | \(2)                           |
+---------------------------------------+--------------------------------+
| ``timedelta = datetime1 - datetime2`` | \(3)                           |
+---------------------------------------+--------------------------------+
| ``datetime1 < datetime2``             | Compares :class:`.datetime` to |
|                                       | :class:`.datetime`. (4)        |
+---------------------------------------+--------------------------------+
868 869 870 871

(1)
   datetime2 is a duration of timedelta removed from datetime1, moving forward in
   time if ``timedelta.days`` > 0, or backward if ``timedelta.days`` < 0.  The
872 873 874 875 876
   result has the same :attr:`tzinfo` attribute as the input datetime, and
   datetime2 - datetime1 == timedelta after. :exc:`OverflowError` is raised if
   datetime2.year would be smaller than :const:`MINYEAR` or larger than
   :const:`MAXYEAR`. Note that no time zone adjustments are done even if the
   input is an aware object.
877 878 879

(2)
   Computes the datetime2 such that datetime2 + timedelta == datetime1. As for
880 881 882 883
   addition, the result has the same :attr:`tzinfo` attribute as the input
   datetime, and no time zone adjustments are done even if the input is aware.
   This isn't quite equivalent to datetime1 + (-timedelta), because -timedelta
   in isolation can overflow in cases where datetime1 - timedelta does not.
884 885

(3)
886
   Subtraction of a :class:`.datetime` from a :class:`.datetime` is defined only if
887 888 889
   both operands are naive, or if both are aware.  If one is aware and the other is
   naive, :exc:`TypeError` is raised.

890 891
   If both are naive, or both are aware and have the same :attr:`tzinfo` attribute,
   the :attr:`tzinfo` attributes are ignored, and the result is a :class:`timedelta`
892 893 894
   object *t* such that ``datetime2 + t == datetime1``.  No time zone adjustments
   are done in this case.

895 896 897 898
   If both are aware and have different :attr:`tzinfo` attributes, ``a-b`` acts
   as if *a* and *b* were first converted to naive UTC datetimes first.  The
   result is ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None)
   - b.utcoffset())`` except that the implementation never overflows.
899 900 901 902 903

(4)
   *datetime1* is considered less than *datetime2* when *datetime1* precedes
   *datetime2* in time.

904 905 906 907
   If one comparand is naive and the other is aware, :exc:`TypeError`
   is raised if an order comparison is attempted.  For equality
   comparisons, naive instances are never equal to aware instances.

908 909 910 911 912
   If both comparands are aware, and have the same :attr:`tzinfo` attribute, the
   common :attr:`tzinfo` attribute is ignored and the base datetimes are
   compared.  If both comparands are aware and have different :attr:`tzinfo`
   attributes, the comparands are first adjusted by subtracting their UTC
   offsets (obtained from ``self.utcoffset()``).
913

914
   .. versionchanged:: 3.3
Éric Araujo's avatar
Éric Araujo committed
915 916
      Equality comparisons between naive and aware :class:`datetime`
      instances don't raise :exc:`TypeError`.
917

918 919 920 921
   .. note::

      In order to stop comparison from falling back to the default scheme of comparing
      object addresses, datetime comparison normally raises :exc:`TypeError` if the
922
      other comparand isn't also a :class:`.datetime` object.  However,
923 924
      ``NotImplemented`` is returned instead if the other comparand has a
      :meth:`timetuple` attribute.  This hook gives other kinds of date objects a
925
      chance at implementing mixed-type comparison.  If not, when a :class:`.datetime`
926 927 928 929
      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.

930 931
:class:`.datetime` objects can be used as dictionary keys. In Boolean contexts,
all :class:`.datetime` objects are considered to be true.
932 933 934 935 936 937 938 939 940 941

Instance methods:

.. method:: datetime.date()

   Return :class:`date` object with same year, month and day.


.. method:: datetime.time()

942
   Return :class:`.time` object with same hour, minute, second and microsecond.
943 944 945 946 947
   :attr:`tzinfo` is ``None``.  See also method :meth:`timetz`.


.. method:: datetime.timetz()

948
   Return :class:`.time` object with same hour, minute, second, microsecond, and
949
   tzinfo attributes.  See also method :meth:`time`.
950 951 952 953


.. method:: datetime.replace([year[, month[, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]]]]])

954 955 956
   Return a datetime with the same attributes, except for those attributes given
   new values by whichever keyword arguments are specified.  Note that
   ``tzinfo=None`` can be specified to create a naive datetime from an aware
957
   datetime with no conversion of date and time data.
958 959


960
.. method:: datetime.astimezone(tz=None)
961

962
   Return a :class:`datetime` object with new :attr:`tzinfo` attribute *tz*,
963
   adjusting the date and time data so the result is the same UTC time as
964
   *self*, but in *tz*'s local time.
965

966
   If provided, *tz* must be an instance of a :class:`tzinfo` subclass, and its
967 968 969 970
   :meth:`utcoffset` and :meth:`dst` methods must not return ``None``.  *self* must
   be aware (``self.tzinfo`` must not be ``None``, and ``self.utcoffset()`` must
   not return ``None``).

971 972 973 974 975
   If called without arguments (or with ``tz=None``) the system local
   timezone is assumed.  The ``tzinfo`` attribute of the converted
   datetime instance will be set to an instance of :class:`timezone`
   with the zone name and offset obtained from the OS.

976
   If ``self.tzinfo`` is *tz*, ``self.astimezone(tz)`` is equal to *self*:  no
977
   adjustment of date or time data is performed. Else the result is local
978 979
   time in time zone *tz*, representing the same UTC time as *self*:  after
   ``astz = dt.astimezone(tz)``, ``astz - astz.utcoffset()`` will usually have
980
   the same date and time data as ``dt - dt.utcoffset()``. The discussion
981 982 983
   of class :class:`tzinfo` explains the cases at Daylight Saving Time transition
   boundaries where this cannot be achieved (an issue only if *tz* models both
   standard and daylight time).
984 985

   If you merely want to attach a time zone object *tz* to a datetime *dt* without
986
   adjustment of date and time data, use ``dt.replace(tzinfo=tz)``.  If you
987
   merely want to remove the time zone object from an aware datetime *dt* without
988
   conversion of date and time data, use ``dt.replace(tzinfo=None)``.
989 990 991 992 993 994 995 996 997 998 999 1000 1001

   Note that the default :meth:`tzinfo.fromutc` method can be overridden in a
   :class:`tzinfo` subclass to affect the result returned by :meth:`astimezone`.
   Ignoring error cases, :meth:`astimezone` acts like::

      def astimezone(self, tz):
          if self.tzinfo is tz:
              return self
          # Convert self to UTC, and attach the new time zone object.
          utc = (self - self.utcoffset()).replace(tzinfo=tz)
          # Convert from UTC to tz's local time.
          return tz.fromutc(utc)

1002 1003 1004
   .. versionchanged:: 3.3
      *tz* now can be omitted.

1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032

.. method:: datetime.utcoffset()

   If :attr:`tzinfo` is ``None``, returns ``None``, else returns
   ``self.tzinfo.utcoffset(self)``, and raises an exception if the latter doesn't
   return ``None``, or a :class:`timedelta` object representing a whole number of
   minutes with magnitude less than one day.


.. method:: datetime.dst()

   If :attr:`tzinfo` is ``None``, returns ``None``, else returns
   ``self.tzinfo.dst(self)``, and raises an exception if the latter doesn't return
   ``None``, or a :class:`timedelta` object representing a whole number of minutes
   with magnitude less than one day.


.. method:: datetime.tzname()

   If :attr:`tzinfo` is ``None``, returns ``None``, else returns
   ``self.tzinfo.tzname(self)``, raises an exception if the latter doesn't return
   ``None`` or a string object,


.. method:: datetime.timetuple()

   Return a :class:`time.struct_time` such as returned by :func:`time.localtime`.
   ``d.timetuple()`` is equivalent to ``time.struct_time((d.year, d.month, d.day,
1033 1034 1035 1036
   d.hour, d.minute, d.second, d.weekday(), yday, dst))``, where ``yday =
   d.toordinal() - date(d.year, 1, 1).toordinal() + 1`` is the day number within
   the current year starting with ``1`` for January 1st. The :attr:`tm_isdst` flag
   of the result is set according to the :meth:`dst` method: :attr:`tzinfo` is
1037
   ``None`` or :meth:`dst` returns ``None``, :attr:`tm_isdst` is set to ``-1``;
1038
   else if :meth:`dst` returns a non-zero value, :attr:`tm_isdst` is set to ``1``;
1039
   else :attr:`tm_isdst` is set to ``0``.
1040 1041 1042 1043


.. method:: datetime.utctimetuple()

1044
   If :class:`.datetime` instance *d* is naive, this is the same as
1045 1046 1047 1048
   ``d.timetuple()`` except that :attr:`tm_isdst` is forced to 0 regardless of what
   ``d.dst()`` returns.  DST is never in effect for a UTC time.

   If *d* is aware, *d* is normalized to UTC time, by subtracting
1049 1050 1051 1052
   ``d.utcoffset()``, and a :class:`time.struct_time` for the
   normalized time is returned.  :attr:`tm_isdst` is forced to 0. Note
   that an :exc:`OverflowError` may be raised if *d*.year was
   ``MINYEAR`` or ``MAXYEAR`` and UTC adjustment spills over a year
1053 1054 1055 1056 1057 1058 1059 1060
   boundary.


.. method:: datetime.toordinal()

   Return the proleptic Gregorian ordinal of the date.  The same as
   ``self.date().toordinal()``.

1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093
.. method:: datetime.timestamp()

   Return POSIX timestamp corresponding to the :class:`datetime`
   instance.  The return value is a :class:`float` similar to that
   returned by :func:`time.time`.

   Naive :class:`datetime` instances are assumed to represent local
   time and this method relies on the platform C :c:func:`mktime`
   function to perform the conversion.  Since :class:`datetime`
   supports wider range of values than :c:func:`mktime` on many
   platforms, this method may raise :exc:`OverflowError` for times far
   in the past or far in the future.

   For aware :class:`datetime` instances, the return value is computed
   as::

      (dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()

   .. versionadded:: 3.3

   .. note::

      There is no method to obtain the POSIX timestamp directly from a
      naive :class:`datetime` instance representing UTC time.  If your
      application uses this convention and your system timezone is not
      set to UTC, you can obtain the POSIX timestamp by supplying
      ``tzinfo=timezone.utc``::

         timestamp = dt.replace(tzinfo=timezone.utc).timestamp()

      or by calculating the timestamp directly::

         timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)
1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113

.. method:: datetime.weekday()

   Return the day of the week as an integer, where Monday is 0 and Sunday is 6.
   The same as ``self.date().weekday()``. See also :meth:`isoweekday`.


.. method:: datetime.isoweekday()

   Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
   The same as ``self.date().isoweekday()``. See also :meth:`weekday`,
   :meth:`isocalendar`.


.. method:: datetime.isocalendar()

   Return a 3-tuple, (ISO year, ISO week number, ISO weekday).  The same as
   ``self.date().isocalendar()``.


1114
.. method:: datetime.isoformat(sep='T')
1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125

   Return a string representing the date and time in ISO 8601 format,
   YYYY-MM-DDTHH:MM:SS.mmmmmm or, if :attr:`microsecond` is 0,
   YYYY-MM-DDTHH:MM:SS

   If :meth:`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 :attr:`microsecond` is 0
   YYYY-MM-DDTHH:MM:SS+HH:MM

   The optional argument *sep* (default ``'T'``) is a one-character separator,
Christian Heimes's avatar
Christian Heimes committed
1126
   placed between the date and time portions of the result.  For example,
1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137

      >>> from datetime import tzinfo, timedelta, datetime
      >>> class TZ(tzinfo):
      ...     def utcoffset(self, dt): return timedelta(minutes=-399)
      ...
      >>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
      '2002-12-25 00:00:00-06:39'


.. method:: datetime.__str__()

1138
   For a :class:`.datetime` instance *d*, ``str(d)`` is equivalent to
1139 1140 1141 1142 1143 1144 1145 1146
   ``d.isoformat(' ')``.


.. method:: datetime.ctime()

   Return a string representing the date and time, for example ``datetime(2002, 12,
   4, 20, 30, 40).ctime() == 'Wed Dec  4 20:30:40 2002'``. ``d.ctime()`` is
   equivalent to ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the
1147
   native C :c:func:`ctime` function (which :func:`time.ctime` invokes, but which
1148 1149 1150 1151 1152 1153
   :meth:`datetime.ctime` does not invoke) conforms to the C standard.


.. method:: datetime.strftime(format)

   Return a string representing the date and time, controlled by an explicit format
Benjamin Peterson's avatar
Benjamin Peterson committed
1154 1155
   string.  See section :ref:`strftime-strptime-behavior`.

1156

Christian Heimes's avatar
Christian Heimes committed
1157 1158 1159 1160
Examples of working with datetime objects:

.. doctest::

1161 1162 1163 1164 1165 1166 1167
    >>> from datetime import datetime, date, time
    >>> # Using datetime.combine()
    >>> d = date(2005, 7, 14)
    >>> t = time(12, 30)
    >>> datetime.combine(d, t)
    datetime.datetime(2005, 7, 14, 12, 30)
    >>> # Using datetime.now() or datetime.utcnow()
Christian Heimes's avatar
Christian Heimes committed
1168
    >>> datetime.now()   # doctest: +SKIP
1169
    datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
Christian Heimes's avatar
Christian Heimes committed
1170
    >>> datetime.utcnow()   # doctest: +SKIP
1171 1172 1173 1174 1175 1176 1177
    datetime.datetime(2007, 12, 6, 15, 29, 43, 79060)
    >>> # Using datetime.strptime()
    >>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
    >>> dt
    datetime.datetime(2006, 11, 21, 16, 30)
    >>> # Using datetime.timetuple() to get tuple of all attributes
    >>> tt = dt.timetuple()
Christian Heimes's avatar
Christian Heimes committed
1178
    >>> for it in tt:   # doctest: +SKIP
1179
    ...     print(it)
1180
    ...
1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191
    2006    # year
    11      # month
    21      # day
    16      # hour
    30      # minute
    0       # second
    1       # weekday (0 = Monday)
    325     # number of days since 1st January
    -1      # dst - method tzinfo.dst() returned None
    >>> # Date in ISO format
    >>> ic = dt.isocalendar()
Christian Heimes's avatar
Christian Heimes committed
1192
    >>> for it in ic:   # doctest: +SKIP
1193
    ...     print(it)
1194 1195 1196 1197 1198 1199 1200 1201
    ...
    2006    # ISO year
    47      # ISO week
    2       # ISO weekday
    >>> # Formatting datetime
    >>> dt.strftime("%A, %d. %B %Y %I:%M%p")
    'Tuesday, 21. November 2006 04:30PM'

Christian Heimes's avatar
Christian Heimes committed
1202
Using datetime with tzinfo:
1203 1204 1205

    >>> from datetime import timedelta, datetime, tzinfo
    >>> class GMT1(tzinfo):
1206 1207 1208 1209
    ...     def utcoffset(self, dt):
    ...         return timedelta(hours=1) + self.dst(dt)
    ...     def dst(self, dt):
    ...         # DST starts last Sunday in March
1210 1211
    ...         d = datetime(dt.year, 4, 1)   # ends last Sunday in October
    ...         self.dston = d - timedelta(days=d.weekday() + 1)
1212
    ...         d = datetime(dt.year, 11, 1)
1213 1214 1215 1216 1217 1218 1219
    ...         self.dstoff = d - timedelta(days=d.weekday() + 1)
    ...         if self.dston <=  dt.replace(tzinfo=None) < self.dstoff:
    ...             return timedelta(hours=1)
    ...         else:
    ...             return timedelta(0)
    ...     def tzname(self,dt):
    ...          return "GMT +1"
1220
    ...
1221
    >>> class GMT2(tzinfo):
1222 1223 1224
    ...     def utcoffset(self, dt):
    ...         return timedelta(hours=2) + self.dst(dt)
    ...     def dst(self, dt):
1225
    ...         d = datetime(dt.year, 4, 1)
1226
    ...         self.dston = d - timedelta(days=d.weekday() + 1)
1227
    ...         d = datetime(dt.year, 11, 1)
1228 1229
    ...         self.dstoff = d - timedelta(days=d.weekday() + 1)
    ...         if self.dston <=  dt.replace(tzinfo=None) < self.dstoff:
1230
    ...             return timedelta(hours=1)
1231 1232 1233 1234
    ...         else:
    ...             return timedelta(0)
    ...     def tzname(self,dt):
    ...         return "GMT +2"
1235
    ...
1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255
    >>> gmt1 = GMT1()
    >>> # Daylight Saving Time
    >>> dt1 = datetime(2006, 11, 21, 16, 30, tzinfo=gmt1)
    >>> dt1.dst()
    datetime.timedelta(0)
    >>> dt1.utcoffset()
    datetime.timedelta(0, 3600)
    >>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=gmt1)
    >>> dt2.dst()
    datetime.timedelta(0, 3600)
    >>> dt2.utcoffset()
    datetime.timedelta(0, 7200)
    >>> # Convert datetime to another time zone
    >>> dt3 = dt2.astimezone(GMT2())
    >>> dt3     # doctest: +ELLIPSIS
    datetime.datetime(2006, 6, 14, 14, 0, tzinfo=<GMT2 object at 0x...>)
    >>> dt2     # doctest: +ELLIPSIS
    datetime.datetime(2006, 6, 14, 13, 0, tzinfo=<GMT1 object at 0x...>)
    >>> dt2.utctimetuple() == dt3.utctimetuple()
    True
1256

1257

1258 1259 1260 1261 1262 1263 1264 1265 1266

.. _datetime-time:

:class:`time` Objects
---------------------

A time object represents a (local) time of day, independent of any particular
day, and subject to adjustment via a :class:`tzinfo` object.

1267
.. class:: time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None)
1268 1269

   All arguments are optional.  *tzinfo* may be ``None``, or an instance of a
1270
   :class:`tzinfo` subclass.  The remaining arguments may be integers, in the
1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285
   following ranges:

   * ``0 <= hour < 24``
   * ``0 <= minute < 60``
   * ``0 <= second < 60``
   * ``0 <= microsecond < 1000000``.

   If an argument outside those ranges is given, :exc:`ValueError` is raised.  All
   default to ``0`` except *tzinfo*, which defaults to :const:`None`.

Class attributes:


.. attribute:: time.min

1286
   The earliest representable :class:`.time`, ``time(0, 0, 0, 0)``.
1287 1288 1289 1290


.. attribute:: time.max

1291
   The latest representable :class:`.time`, ``time(23, 59, 59, 999999)``.
1292 1293 1294 1295


.. attribute:: time.resolution

1296 1297 1298
   The smallest possible difference between non-equal :class:`.time` objects,
   ``timedelta(microseconds=1)``, although note that arithmetic on
   :class:`.time` objects is not supported.
1299 1300


Benjamin Peterson's avatar
Benjamin Peterson committed
1301
Instance attributes (read-only):
1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324

.. attribute:: time.hour

   In ``range(24)``.


.. attribute:: time.minute

   In ``range(60)``.


.. attribute:: time.second

   In ``range(60)``.


.. attribute:: time.microsecond

   In ``range(1000000)``.


.. attribute:: time.tzinfo

1325
   The object passed as the tzinfo argument to the :class:`.time` constructor, or
1326 1327
   ``None`` if none was passed.

Benjamin Peterson's avatar
Benjamin Peterson committed
1328

1329 1330
Supported operations:

1331
* comparison of :class:`.time` to :class:`.time`, where *a* is considered less
1332
  than *b* when *a* precedes *b* in time.  If one comparand is naive and the other
1333 1334 1335 1336
  is aware, :exc:`TypeError` is raised if an order comparison is attempted. For equality
  comparisons, naive instances are never equal to aware instances.

  If both comparands are aware, and have
1337 1338 1339 1340 1341
  the same :attr:`tzinfo` attribute, the common :attr:`tzinfo` attribute is
  ignored and the base times are compared.  If both comparands are aware and
  have different :attr:`tzinfo` attributes, the comparands are first adjusted by
  subtracting their UTC offsets (obtained from ``self.utcoffset()``). In order
  to stop mixed-type comparisons from falling back to the default comparison by
1342
  object address, when a :class:`.time` object is compared to an object of a
1343
  different type, :exc:`TypeError` is raised unless the comparison is ``==`` or
1344
  ``!=``.  The latter cases return :const:`False` or :const:`True`, respectively.
1345

1346
  .. versionchanged:: 3.3
Éric Araujo's avatar
Éric Araujo committed
1347 1348
     Equality comparisons between naive and aware :class:`time` instances
     don't raise :exc:`TypeError`.
1349

1350 1351 1352 1353
* hash, use as dict key

* efficient pickling

1354
* in Boolean contexts, a :class:`.time` object is considered to be true if and
1355 1356 1357 1358
  only if, after converting it to minutes and subtracting :meth:`utcoffset` (or
  ``0`` if that's ``None``), the result is non-zero.


Benjamin Peterson's avatar
Benjamin Peterson committed
1359
Instance methods:
1360 1361 1362

.. method:: time.replace([hour[, minute[, second[, microsecond[, tzinfo]]]]])

1363
   Return a :class:`.time` with the same value, except for those attributes given
1364
   new values by whichever keyword arguments are specified.  Note that
1365 1366
   ``tzinfo=None`` can be specified to create a naive :class:`.time` from an
   aware :class:`.time`, without conversion of the time data.
1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384


.. method:: time.isoformat()

   Return a string representing the time in ISO 8601 format, HH:MM:SS.mmmmmm or, if
   self.microsecond is 0, HH:MM:SS If :meth:`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, HH:MM:SS+HH:MM


.. method:: time.__str__()

   For a time *t*, ``str(t)`` is equivalent to ``t.isoformat()``.


.. method:: time.strftime(format)

   Return a string representing the time, controlled by an explicit format string.
Benjamin Peterson's avatar
Benjamin Peterson committed
1385
   See section :ref:`strftime-strptime-behavior`.
1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409


.. method:: time.utcoffset()

   If :attr:`tzinfo` is ``None``, returns ``None``, else returns
   ``self.tzinfo.utcoffset(None)``, and raises an exception if the latter doesn't
   return ``None`` or a :class:`timedelta` object representing a whole number of
   minutes with magnitude less than one day.


.. method:: time.dst()

   If :attr:`tzinfo` is ``None``, returns ``None``, else returns
   ``self.tzinfo.dst(None)``, and raises an exception if the latter doesn't return
   ``None``, or a :class:`timedelta` object representing a whole number of minutes
   with magnitude less than one day.


.. method:: time.tzname()

   If :attr:`tzinfo` is ``None``, returns ``None``, else returns
   ``self.tzinfo.tzname(None)``, or raises an exception if the latter doesn't
   return ``None`` or a string object.

Benjamin Peterson's avatar
Benjamin Peterson committed
1410

Christian Heimes's avatar
Christian Heimes committed
1411
Example:
1412

1413 1414 1415
    >>> from datetime import time, tzinfo
    >>> class GMT1(tzinfo):
    ...     def utcoffset(self, dt):
1416 1417
    ...         return timedelta(hours=1)
    ...     def dst(self, dt):
1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434
    ...         return timedelta(0)
    ...     def tzname(self,dt):
    ...         return "Europe/Prague"
    ...
    >>> t = time(12, 10, 30, tzinfo=GMT1())
    >>> t                               # doctest: +ELLIPSIS
    datetime.time(12, 10, 30, tzinfo=<GMT1 object at 0x...>)
    >>> gmt = GMT1()
    >>> t.isoformat()
    '12:10:30+01:00'
    >>> t.dst()
    datetime.timedelta(0)
    >>> t.tzname()
    'Europe/Prague'
    >>> t.strftime("%H:%M:%S %Z")
    '12:10:30 Europe/Prague'

1435 1436 1437 1438 1439 1440

.. _datetime-tzinfo:

:class:`tzinfo` Objects
-----------------------

1441
:class:`tzinfo` is an abstract base class, meaning that this class should not be
1442 1443
instantiated directly.  You need to derive a concrete subclass, and (at least)
supply implementations of the standard :class:`tzinfo` methods needed by the
1444
:class:`.datetime` methods you use.  The :mod:`datetime` module supplies
1445 1446 1447
a simple concrete subclass of :class:`tzinfo` :class:`timezone` which can reprsent
timezones with fixed offset from UTC such as UTC itself or North American EST and
EDT.
1448 1449

An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the
1450
constructors for :class:`.datetime` and :class:`.time` objects. The latter objects
1451
view their attributes as being in local time, and the :class:`tzinfo` object
1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464
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.

Special requirement for pickling:  A :class:`tzinfo` subclass must have an
:meth:`__init__` method that can be called with no arguments, else it can be
pickled but possibly not unpickled again.  This is a technical requirement that
may be relaxed in the future.

A concrete subclass of :class:`tzinfo` may need to implement the following
methods.  Exactly which methods are needed depends on the uses made of aware
:mod:`datetime` objects.  If in doubt, simply implement all of them.


1465
.. method:: tzinfo.utcoffset(dt)
1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486

   Return offset of local time from UTC, in minutes east of UTC.  If local time is
   west of UTC, this should be negative.  Note that this is intended to be the
   total offset from UTC; for example, if a :class:`tzinfo` object represents both
   time zone and DST adjustments, :meth:`utcoffset` should return their sum.  If
   the UTC offset isn't known, return ``None``.  Else the value returned must be a
   :class:`timedelta` object specifying a whole number of minutes in the range
   -1439 to 1439 inclusive (1440 = 24\*60; the magnitude of the offset must be less
   than one day).  Most implementations of :meth:`utcoffset` will probably look
   like one of these two::

      return CONSTANT                 # fixed-offset class
      return CONSTANT + self.dst(dt)  # daylight-aware class

   If :meth:`utcoffset` does not return ``None``, :meth:`dst` should not return
   ``None`` either.

   The default implementation of :meth:`utcoffset` raises
   :exc:`NotImplementedError`.


1487
.. method:: tzinfo.dst(dt)
1488 1489 1490 1491 1492 1493 1494 1495

   Return the daylight saving time (DST) adjustment, in minutes east of UTC, or
   ``None`` if DST information isn't known.  Return ``timedelta(0)`` if DST is not
   in effect. If DST is in effect, return the offset as a :class:`timedelta` object
   (see :meth:`utcoffset` for details). Note that DST offset, if applicable, has
   already been added to the UTC offset returned by :meth:`utcoffset`, so there's
   no need to consult :meth:`dst` unless you're interested in obtaining DST info
   separately.  For example, :meth:`datetime.timetuple` calls its :attr:`tzinfo`
1496 1497 1498
   attribute's :meth:`dst` method to determine how the :attr:`tm_isdst` flag
   should be set, and :meth:`tzinfo.fromutc` calls :meth:`dst` to account for
   DST changes when crossing time zones.
1499 1500 1501 1502 1503 1504

   An instance *tz* of a :class:`tzinfo` subclass that models both standard and
   daylight times must be consistent in this sense:

   ``tz.utcoffset(dt) - tz.dst(dt)``

1505
   must return the same result for every :class:`.datetime` *dt* with ``dt.tzinfo ==
1506 1507 1508 1509 1510 1511 1512 1513 1514 1515
   tz``  For sane :class:`tzinfo` subclasses, this expression yields the time
   zone's "standard offset", which should not depend on the date or the time, but
   only on geographic location.  The implementation of :meth:`datetime.astimezone`
   relies on this, but cannot detect violations; it's the programmer's
   responsibility to ensure it.  If a :class:`tzinfo` subclass cannot guarantee
   this, it may be able to override the default implementation of
   :meth:`tzinfo.fromutc` to work correctly with :meth:`astimezone` regardless.

   Most implementations of :meth:`dst` will probably look like one of these two::

1516
      def dst(self, dt):
1517 1518 1519 1520 1521
          # a fixed-offset class:  doesn't account for DST
          return timedelta(0)

   or ::

1522
      def dst(self, dt):
1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534
          # Code to set dston and dstoff to the time zone's DST
          # transition times based on the input dt.year, and expressed
          # in standard local time.  Then

          if dston <= dt.replace(tzinfo=None) < dstoff:
              return timedelta(hours=1)
          else:
              return timedelta(0)

   The default implementation of :meth:`dst` raises :exc:`NotImplementedError`.


1535
.. method:: tzinfo.tzname(dt)
1536

1537
   Return the time zone name corresponding to the :class:`.datetime` object *dt*, as
1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548
   a string. Nothing about string names is defined by the :mod:`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 :class:`tzinfo`
   subclasses will wish to return different names depending on the specific value
   of *dt* passed, especially if the :class:`tzinfo` class is accounting for
   daylight time.

   The default implementation of :meth:`tzname` raises :exc:`NotImplementedError`.

Benjamin Peterson's avatar
Benjamin Peterson committed
1549

1550 1551 1552
These methods are called by a :class:`.datetime` or :class:`.time` object, in
response to their methods of the same names.  A :class:`.datetime` object passes
itself as the argument, and a :class:`.time` object passes ``None`` as the
1553
argument.  A :class:`tzinfo` subclass's methods should therefore be prepared to
1554
accept a *dt* argument of ``None``, or of class :class:`.datetime`.
1555 1556 1557 1558 1559 1560 1561

When ``None`` is passed, it's up to the class designer to decide the best
response.  For example, returning ``None`` is appropriate if the class wishes to
say that time objects don't participate in the :class:`tzinfo` protocols.  It
may be more useful for ``utcoffset(None)`` to return the standard UTC offset, as
there is no other convention for discovering the standard offset.

1562
When a :class:`.datetime` object is passed in response to a :class:`.datetime`
1563 1564 1565 1566 1567 1568 1569 1570
method, ``dt.tzinfo`` is the same object as *self*.  :class:`tzinfo` methods can
rely on this, unless user code calls :class:`tzinfo` methods directly.  The
intent is that the :class:`tzinfo` methods interpret *dt* as being in local
time, and not need worry about objects in other timezones.

There is one more :class:`tzinfo` method that a subclass may wish to override:


1571
.. method:: tzinfo.fromutc(dt)
1572

1573 1574 1575 1576
   This is called from the default :class:`datetime.astimezone()`
   implementation.  When called from that, ``dt.tzinfo`` is *self*, and *dt*'s
   date and time data are to be viewed as expressing a UTC time.  The purpose
   of :meth:`fromutc` is to adjust the date and time data, returning an
1577
   equivalent datetime in *self*'s local time.
1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614

   Most :class:`tzinfo` subclasses should be able to inherit the default
   :meth:`fromutc` implementation without problems.  It's strong enough to handle
   fixed-offset time zones, and time zones accounting for both standard and
   daylight time, and the latter even if the DST transition times differ in
   different years.  An example of a time zone the default :meth:`fromutc`
   implementation may not handle correctly in all cases is one where the standard
   offset (from UTC) depends on the specific date and time passed, which can happen
   for political reasons. The default implementations of :meth:`astimezone` and
   :meth:`fromutc` may not produce the result you want if the result is one of the
   hours straddling the moment the standard offset changes.

   Skipping code for error cases, the default :meth:`fromutc` implementation acts
   like::

      def fromutc(self, dt):
          # raise ValueError error if dt.tzinfo is not self
          dtoff = dt.utcoffset()
          dtdst = dt.dst()
          # raise ValueError if dtoff is None or dtdst is None
          delta = dtoff - dtdst  # this is self's standard offset
          if delta:
              dt += delta   # convert to standard local time
              dtdst = dt.dst()
              # raise ValueError if dtdst is None
          if dtdst:
              return dt + dtdst
          else:
              return dt

Example :class:`tzinfo` classes:

.. literalinclude:: ../includes/tzinfo-examples.py

Note that there are unavoidable subtleties twice per year in a :class:`tzinfo`
subclass accounting for both standard and daylight time, at the DST transition
points.  For concreteness, consider US Eastern (UTC -0500), where EDT begins the
1615 1616
minute after 1:59 (EST) on the second Sunday in March, and ends the minute after
1:59 (EDT) on the first Sunday in November::
1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629

     UTC   3:MM  4:MM  5:MM  6:MM  7:MM  8:MM
     EST  22:MM 23:MM  0:MM  1:MM  2:MM  3:MM
     EDT  23:MM  0:MM  1:MM  2:MM  3:MM  4:MM

   start  22:MM 23:MM  0:MM  1:MM  3:MM  4:MM

     end  23:MM  0:MM  1:MM  1:MM  2:MM  3:MM

When DST starts (the "start" line), the local wall clock leaps from 1:59 to
3:00.  A wall time of the form 2:MM doesn't really make sense on that day, so
``astimezone(Eastern)`` won't deliver a result with ``hour == 2`` on the day DST
begins.  In order for :meth:`astimezone` to make this guarantee, the
1630
:meth:`tzinfo.dst` method must consider times in the "missing hour" (2:MM for
1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646
Eastern) to be in daylight time.

When DST ends (the "end" line), there's a potentially worse problem: there's an
hour that can't be spelled unambiguously in local wall time: the last hour of
daylight time.  In Eastern, that's times of the form 5:MM UTC on the day
daylight time ends.  The local wall clock leaps from 1:59 (daylight time) back
to 1:00 (standard time) again. Local times of the form 1:MM are ambiguous.
:meth:`astimezone` mimics the local clock's behavior by mapping two adjacent UTC
hours into the same local hour then.  In the Eastern example, UTC times of the
form 5:MM and 6:MM both map to 1:MM when converted to Eastern.  In order for
:meth:`astimezone` to make this guarantee, the :meth:`tzinfo.dst` method must
consider times in the "repeated hour" to be in standard time.  This is easily
arranged, as in the example, by expressing DST switch times in the time zone's
standard local time.

Applications that can't bear such ambiguities should avoid using hybrid
1647 1648 1649 1650
:class:`tzinfo` subclasses; there are no ambiguities when using :class:`timezone`,
or any other fixed-offset :class:`tzinfo` subclass (such as a class representing
only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).

1651 1652 1653
.. seealso::

   `pytz <http://pypi.python.org/pypi/pytz/>`_
1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665
      The standard library has no :class:`tzinfo` instances except for UTC, but
      there exists a third-party library which brings the *IANA timezone
      database* (also known as the Olson database) to Python: *pytz*.

      *pytz* contains up-to-date information and its usage is recommended.

   `IANA timezone database <http://www.iana.org/time-zones>`_
      The Time Zone Database (often called tz or zoneinfo) contains code and
      data that represent the history of local time for many representative
      locations around the globe. It is updated periodically to reflect changes
      made by political bodies to time zone boundaries, UTC offsets, and
      daylight-saving rules.
1666

1667 1668 1669 1670 1671 1672

.. _datetime-timezone:

:class:`timezone` Objects
--------------------------

1673 1674 1675 1676 1677 1678
The :class:`timezone` class is a subclass of :class:`tzinfo`, each
instance of which represents a timezone defined by a fixed offset from
UTC.  Note that objects of this class cannot be used to represent
timezone information in the locations where different offsets are used
in different days of the year or where historical changes have been
made to civil time.
1679 1680 1681 1682


.. class:: timezone(offset[, name])

1683
  The *offset* argument must be specified as a :class:`timedelta`
1684
  object representing the difference between the local time and UTC.  It must
1685 1686
  be strictly between ``-timedelta(hours=24)`` and
  ``timedelta(hours=24)`` and represent a whole number of minutes,
1687 1688
  otherwise :exc:`ValueError` is raised.

1689 1690
  The *name* argument is optional.  If specified it must be a string that
  is used as the value returned by the ``tzname(dt)`` method.  Otherwise,
1691
  ``tzname(dt)`` returns a string 'UTCsHH:MM', where s is the sign of
1692
  *offset*, HH and MM are two digits of ``offset.hours`` and
1693 1694
  ``offset.minutes`` respectively.

1695
.. method:: timezone.utcoffset(dt)
1696

1697 1698
  Return the fixed value specified when the :class:`timezone` instance is
  constructed.  The *dt* argument is ignored.  The return value is a
1699 1700 1701
  :class:`timedelta` instance equal to the difference between the
  local time and UTC.

1702
.. method:: timezone.tzname(dt)
1703

1704
  Return the fixed value specified when the :class:`timezone` instance is
1705
  constructed or a string 'UTCsHH:MM', where s is the sign of
1706 1707
  *offset*, HH and MM are two digits of ``offset.hours`` and
  ``offset.minutes`` respectively.
1708

1709
.. method:: timezone.dst(dt)
1710 1711 1712

  Always returns ``None``.

1713
.. method:: timezone.fromutc(dt)
1714

1715
  Return ``dt + offset``.  The *dt* argument must be an aware
1716
  :class:`.datetime` instance, with ``tzinfo`` set to ``self``.
1717 1718 1719 1720 1721

Class attributes:

.. attribute:: timezone.utc

1722
   The UTC timezone, ``timezone(timedelta(0))``.
1723

1724

Benjamin Peterson's avatar
Benjamin Peterson committed
1725
.. _strftime-strptime-behavior:
1726

Benjamin Peterson's avatar
Benjamin Peterson committed
1727 1728
:meth:`strftime` and :meth:`strptime` Behavior
----------------------------------------------
1729

1730
:class:`date`, :class:`.datetime`, and :class:`.time` objects all support a
1731 1732 1733 1734 1735
``strftime(format)`` method, to create a string representing the time under the
control of an explicit format string.  Broadly speaking, ``d.strftime(fmt)``
acts like the :mod:`time` module's ``time.strftime(fmt, d.timetuple())``
although not all objects support a :meth:`timetuple` method.

Benjamin Peterson's avatar
Benjamin Peterson committed
1736
Conversely, the :meth:`datetime.strptime` class method creates a
1737
:class:`.datetime` object from a string representing a date and time and a
Benjamin Peterson's avatar
Benjamin Peterson committed
1738 1739 1740
corresponding format string. ``datetime.strptime(date_string, format)`` is
equivalent to ``datetime(*(time.strptime(date_string, format)[0:6]))``.

1741
For :class:`.time` objects, the format codes for year, month, and day should not
1742
be used, as time objects have no such values.  If they're used anyway, ``1900``
Benjamin Peterson's avatar
Benjamin Peterson committed
1743
is substituted for the year, and ``1`` for the month and day.
1744

Christian Heimes's avatar
Christian Heimes committed
1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763
For :class:`date` objects, the format codes for hours, minutes, seconds, and
microseconds should not be used, as :class:`date` objects have no such
values.  If they're used anyway, ``0`` is substituted for them.

For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty
strings.

For an aware object:

``%z``
   :meth:`utcoffset` is transformed into a 5-character string of the form +HHMM or
   -HHMM, 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.  For example, if
   :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is
   replaced with the string ``'-0330'``.

``%Z``
   If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty string.
   Otherwise ``%Z`` is replaced by the returned value, which must be a string.
1764 1765 1766

The full set of format codes supported varies across platforms, because Python
calls the platform C library's :func:`strftime` function, and platform
1767
variations are common.
1768 1769 1770 1771 1772

The following is a list of all the format codes that the C standard (1989
version) requires, and these work on all platforms with a standard C
implementation.  Note that the 1999 version of the C standard added additional
format codes.
1773

1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792
+-----------+--------------------------------+-------+
| Directive | Meaning                        | Notes |
+===========+================================+=======+
| ``%a``    | Locale's abbreviated weekday   |       |
|           | name.                          |       |
+-----------+--------------------------------+-------+
| ``%A``    | Locale's full weekday name.    |       |
+-----------+--------------------------------+-------+
| ``%b``    | Locale's abbreviated month     |       |
|           | name.                          |       |
+-----------+--------------------------------+-------+
| ``%B``    | Locale's full month name.      |       |
+-----------+--------------------------------+-------+
| ``%c``    | Locale's appropriate date and  |       |
|           | time representation.           |       |
+-----------+--------------------------------+-------+
| ``%d``    | Day of the month as a decimal  |       |
|           | number [01,31].                |       |
+-----------+--------------------------------+-------+
Christian Heimes's avatar
Christian Heimes committed
1793 1794 1795 1796
| ``%f``    | Microsecond as a decimal       | \(1)  |
|           | number [0,999999], zero-padded |       |
|           | on the left                    |       |
+-----------+--------------------------------+-------+
1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811
| ``%H``    | Hour (24-hour clock) as a      |       |
|           | decimal number [00,23].        |       |
+-----------+--------------------------------+-------+
| ``%I``    | Hour (12-hour clock) as a      |       |
|           | decimal number [01,12].        |       |
+-----------+--------------------------------+-------+
| ``%j``    | Day of the year as a decimal   |       |
|           | number [001,366].              |       |
+-----------+--------------------------------+-------+
| ``%m``    | Month as a decimal number      |       |
|           | [01,12].                       |       |
+-----------+--------------------------------+-------+
| ``%M``    | Minute as a decimal number     |       |
|           | [00,59].                       |       |
+-----------+--------------------------------+-------+
Christian Heimes's avatar
Christian Heimes committed
1812
| ``%p``    | Locale's equivalent of either  | \(2)  |
1813 1814
|           | AM or PM.                      |       |
+-----------+--------------------------------+-------+
Christian Heimes's avatar
Christian Heimes committed
1815
| ``%S``    | Second as a decimal number     | \(3)  |
1816
|           | [00,59].                       |       |
1817
+-----------+--------------------------------+-------+
Christian Heimes's avatar
Christian Heimes committed
1818
| ``%U``    | Week number of the year        | \(4)  |
1819 1820 1821 1822 1823 1824 1825 1826 1827 1828
|           | (Sunday as the first day of    |       |
|           | the week) as a decimal number  |       |
|           | [00,53].  All days in a new    |       |
|           | year preceding the first       |       |
|           | Sunday are considered to be in |       |
|           | week 0.                        |       |
+-----------+--------------------------------+-------+
| ``%w``    | Weekday as a decimal number    |       |
|           | [0(Sunday),6].                 |       |
+-----------+--------------------------------+-------+
Christian Heimes's avatar
Christian Heimes committed
1829
| ``%W``    | Week number of the year        | \(4)  |
1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845
|           | (Monday as the first day of    |       |
|           | the week) as a decimal number  |       |
|           | [00,53].  All days in a new    |       |
|           | year preceding the first       |       |
|           | Monday are considered to be in |       |
|           | week 0.                        |       |
+-----------+--------------------------------+-------+
| ``%x``    | Locale's appropriate date      |       |
|           | representation.                |       |
+-----------+--------------------------------+-------+
| ``%X``    | Locale's appropriate time      |       |
|           | representation.                |       |
+-----------+--------------------------------+-------+
| ``%y``    | Year without century as a      |       |
|           | decimal number [00,99].        |       |
+-----------+--------------------------------+-------+
1846
| ``%Y``    | Year with century as a decimal | \(5)  |
1847
|           | number [0001,9999].            |       |
1848
+-----------+--------------------------------+-------+
1849
| ``%z``    | UTC offset in the form +HHMM   | \(6)  |
1850 1851 1852 1853 1854 1855 1856 1857
|           | or -HHMM (empty string if the  |       |
|           | the object is naive).          |       |
+-----------+--------------------------------+-------+
| ``%Z``    | Time zone name (empty string   |       |
|           | if the object is naive).       |       |
+-----------+--------------------------------+-------+
| ``%%``    | A literal ``'%'`` character.   |       |
+-----------+--------------------------------+-------+
1858

1859 1860 1861
Notes:

(1)
Benjamin Peterson's avatar
Benjamin Peterson committed
1862
   When used with the :meth:`strptime` method, the ``%f`` directive
Christian Heimes's avatar
Christian Heimes committed
1863
   accepts from one to six digits and zero pads on the right.  ``%f`` is
1864 1865 1866
   an extension to the set of format characters in the C standard (but
   implemented separately in datetime objects, and therefore always
   available).
Christian Heimes's avatar
Christian Heimes committed
1867 1868

(2)
Benjamin Peterson's avatar
Benjamin Peterson committed
1869
   When used with the :meth:`strptime` method, the ``%p`` directive only affects
1870 1871
   the output hour field if the ``%I`` directive is used to parse the hour.

Christian Heimes's avatar
Christian Heimes committed
1872
(3)
1873 1874
   Unlike :mod:`time` module, :mod:`datetime` module does not support
   leap seconds.
1875

Christian Heimes's avatar
Christian Heimes committed
1876
(4)
Benjamin Peterson's avatar
Benjamin Peterson committed
1877
   When used with the :meth:`strptime` method, ``%U`` and ``%W`` are only used in
1878 1879
   calculations when the day of the week and the year are specified.

Christian Heimes's avatar
Christian Heimes committed
1880
(5)
1881
   The :meth:`strptime` method can
1882 1883
   parse years in the full [1, 9999] range, but years < 1000 must be
   zero-filled to 4-digit width.
1884 1885 1886 1887 1888

   .. versionchanged:: 3.2
      In previous versions, :meth:`strftime` method was restricted to
      years >= 1900.

1889 1890 1891 1892
   .. versionchanged:: 3.3
      In version 3.2, :meth:`strftime` method was restricted to
      years >= 1000.

1893
(6)
1894 1895
   For example, if :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``,
   ``%z`` is replaced with the string ``'-0330'``.
1896

1897 1898
.. versionchanged:: 3.2
   When the ``%z`` directive is provided to the :meth:`strptime` method, an
1899
   aware :class:`.datetime` object will be produced.  The ``tzinfo`` of the
1900
   result will be set to a :class:`timezone` instance.
1901 1902 1903 1904

.. rubric:: Footnotes

.. [#] If, that is, we ignore the effects of Relativity