PageRenderTime 891ms CodeModel.GetById 221ms app.highlight 421ms RepoModel.GetById 127ms app.codeStats 0ms

/Doc/library/datetime.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 1645 lines | 1188 code | 457 blank | 0 comment | 0 complexity | 35f9318c3b6eef10d8bea0174ae83f83 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1:mod:`datetime` --- Basic date and time types
   2=============================================
   3
   4.. module:: datetime
   5   :synopsis: Basic date and time types.
   6.. moduleauthor:: Tim Peters <tim@zope.com>
   7.. sectionauthor:: Tim Peters <tim@zope.com>
   8.. sectionauthor:: A.M. Kuchling <amk@amk.ca>
   9
  10.. XXX what order should the types be discussed in?
  11
  12.. versionadded:: 2.3
  13
  14The :mod:`datetime` module supplies classes for manipulating dates and times in
  15both simple and complex ways.  While date and time arithmetic is supported, the
  16focus of the implementation is on efficient member extraction for output
  17formatting and manipulation. For related
  18functionality, see also the :mod:`time` and :mod:`calendar` modules.
  19
  20There are two kinds of date and time objects: "naive" and "aware". This
  21distinction refers to whether the object has any notion of time zone, daylight
  22saving time, or other kind of algorithmic or political time adjustment.  Whether
  23a naive :class:`datetime` object represents Coordinated Universal Time (UTC),
  24local time, or time in some other timezone is purely up to the program, just
  25like it's up to the program whether a particular number represents metres,
  26miles, or mass.  Naive :class:`datetime` objects are easy to understand and to
  27work with, at the cost of ignoring some aspects of reality.
  28
  29For applications requiring more, :class:`datetime` and :class:`time` objects
  30have an optional time zone information member, :attr:`tzinfo`, that can contain
  31an instance of a subclass of the abstract :class:`tzinfo` class.  These
  32:class:`tzinfo` objects capture information about the offset from UTC time, the
  33time zone name, and whether Daylight Saving Time is in effect.  Note that no
  34concrete :class:`tzinfo` classes are supplied by the :mod:`datetime` module.
  35Supporting timezones at whatever level of detail is required is up to the
  36application.  The rules for time adjustment across the world are more political
  37than rational, and there is no standard suitable for every application.
  38
  39The :mod:`datetime` module exports the following constants:
  40
  41
  42.. data:: MINYEAR
  43
  44   The smallest year number allowed in a :class:`date` or :class:`datetime` object.
  45   :const:`MINYEAR` is ``1``.
  46
  47
  48.. data:: MAXYEAR
  49
  50   The largest year number allowed in a :class:`date` or :class:`datetime` object.
  51   :const:`MAXYEAR` is ``9999``.
  52
  53
  54.. seealso::
  55
  56   Module :mod:`calendar`
  57      General calendar related functions.
  58
  59   Module :mod:`time`
  60      Time access and conversions.
  61
  62
  63Available Types
  64---------------
  65
  66
  67.. class:: date
  68
  69   An idealized naive date, assuming the current Gregorian calendar always was, and
  70   always will be, in effect. Attributes: :attr:`year`, :attr:`month`, and
  71   :attr:`day`.
  72
  73
  74.. class:: time
  75
  76   An idealized time, independent of any particular day, assuming that every day
  77   has exactly 24\*60\*60 seconds (there is no notion of "leap seconds" here).
  78   Attributes: :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,
  79   and :attr:`tzinfo`.
  80
  81
  82.. class:: datetime
  83
  84   A combination of a date and a time. Attributes: :attr:`year`, :attr:`month`,
  85   :attr:`day`, :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,
  86   and :attr:`tzinfo`.
  87
  88
  89.. class:: timedelta
  90
  91   A duration expressing the difference between two :class:`date`, :class:`time`,
  92   or :class:`datetime` instances to microsecond resolution.
  93
  94
  95.. class:: tzinfo
  96
  97   An abstract base class for time zone information objects.  These are used by the
  98   :class:`datetime` and :class:`time` classes to provide a customizable notion of
  99   time adjustment (for example, to account for time zone and/or daylight saving
 100   time).
 101
 102Objects of these types are immutable.
 103
 104Objects of the :class:`date` type are always naive.
 105
 106An object *d* of type :class:`time` or :class:`datetime` may be naive or aware.
 107*d* is aware if ``d.tzinfo`` is not ``None`` and ``d.tzinfo.utcoffset(d)`` does
 108not return ``None``.  If ``d.tzinfo`` is ``None``, or if ``d.tzinfo`` is not
 109``None`` but ``d.tzinfo.utcoffset(d)`` returns ``None``, *d* is naive.
 110
 111The distinction between naive and aware doesn't apply to :class:`timedelta`
 112objects.
 113
 114Subclass relationships::
 115
 116   object
 117       timedelta
 118       tzinfo
 119       time
 120       date
 121           datetime
 122
 123
 124.. _datetime-timedelta:
 125
 126:class:`timedelta` Objects
 127--------------------------
 128
 129A :class:`timedelta` object represents a duration, the difference between two
 130dates or times.
 131
 132
 133.. class:: timedelta([days[, seconds[, microseconds[, milliseconds[, minutes[, hours[, weeks]]]]]]])
 134
 135   All arguments are optional and default to ``0``.  Arguments may be ints, longs,
 136   or floats, and may be positive or negative.
 137
 138   Only *days*, *seconds* and *microseconds* are stored internally.  Arguments are
 139   converted to those units:
 140
 141   * A millisecond is converted to 1000 microseconds.
 142   * A minute is converted to 60 seconds.
 143   * An hour is converted to 3600 seconds.
 144   * A week is converted to 7 days.
 145
 146   and days, seconds and microseconds are then normalized so that the
 147   representation is unique, with
 148
 149   * ``0 <= microseconds < 1000000``
 150   * ``0 <= seconds < 3600*24`` (the number of seconds in one day)
 151   * ``-999999999 <= days <= 999999999``
 152
 153   If any argument is a float and there are fractional microseconds, the fractional
 154   microseconds left over from all arguments are combined and their sum is rounded
 155   to the nearest microsecond.  If no argument is a float, the conversion and
 156   normalization processes are exact (no information is lost).
 157
 158   If the normalized value of days lies outside the indicated range,
 159   :exc:`OverflowError` is raised.
 160
 161   Note that normalization of negative values may be surprising at first. For
 162   example,
 163
 164      >>> from datetime import timedelta
 165      >>> d = timedelta(microseconds=-1)
 166      >>> (d.days, d.seconds, d.microseconds)
 167      (-1, 86399, 999999)
 168
 169Class attributes are:
 170
 171
 172.. attribute:: timedelta.min
 173
 174   The most negative :class:`timedelta` object, ``timedelta(-999999999)``.
 175
 176
 177.. attribute:: timedelta.max
 178
 179   The most positive :class:`timedelta` object, ``timedelta(days=999999999,
 180   hours=23, minutes=59, seconds=59, microseconds=999999)``.
 181
 182
 183.. attribute:: timedelta.resolution
 184
 185   The smallest possible difference between non-equal :class:`timedelta` objects,
 186   ``timedelta(microseconds=1)``.
 187
 188Note that, because of normalization, ``timedelta.max`` > ``-timedelta.min``.
 189``-timedelta.max`` is not representable as a :class:`timedelta` object.
 190
 191Instance attributes (read-only):
 192
 193+------------------+--------------------------------------------+
 194| Attribute        | Value                                      |
 195+==================+============================================+
 196| ``days``         | Between -999999999 and 999999999 inclusive |
 197+------------------+--------------------------------------------+
 198| ``seconds``      | Between 0 and 86399 inclusive              |
 199+------------------+--------------------------------------------+
 200| ``microseconds`` | Between 0 and 999999 inclusive             |
 201+------------------+--------------------------------------------+
 202
 203Supported operations:
 204
 205.. XXX this table is too wide!
 206
 207+--------------------------------+-----------------------------------------------+
 208| Operation                      | Result                                        |
 209+================================+===============================================+
 210| ``t1 = t2 + t3``               | Sum of *t2* and *t3*. Afterwards *t1*-*t2* == |
 211|                                | *t3* and *t1*-*t3* == *t2* are true. (1)      |
 212+--------------------------------+-----------------------------------------------+
 213| ``t1 = t2 - t3``               | Difference of *t2* and *t3*. Afterwards *t1*  |
 214|                                | == *t2* - *t3* and *t2* == *t1* + *t3* are    |
 215|                                | true. (1)                                     |
 216+--------------------------------+-----------------------------------------------+
 217| ``t1 = t2 * i or t1 = i * t2`` | Delta multiplied by an integer or long.       |
 218|                                | Afterwards *t1* // i == *t2* is true,         |
 219|                                | provided ``i != 0``.                          |
 220+--------------------------------+-----------------------------------------------+
 221|                                | In general, *t1* \* i == *t1* \* (i-1) + *t1* |
 222|                                | is true. (1)                                  |
 223+--------------------------------+-----------------------------------------------+
 224| ``t1 = t2 // i``               | The floor is computed and the remainder (if   |
 225|                                | any) is thrown away. (3)                      |
 226+--------------------------------+-----------------------------------------------+
 227| ``+t1``                        | Returns a :class:`timedelta` object with the  |
 228|                                | same value. (2)                               |
 229+--------------------------------+-----------------------------------------------+
 230| ``-t1``                        | equivalent to :class:`timedelta`\             |
 231|                                | (-*t1.days*, -*t1.seconds*,                   |
 232|                                | -*t1.microseconds*), and to *t1*\* -1. (1)(4) |
 233+--------------------------------+-----------------------------------------------+
 234| ``abs(t)``                     | equivalent to +*t* when ``t.days >= 0``, and  |
 235|                                | to -*t* when ``t.days < 0``. (2)              |
 236+--------------------------------+-----------------------------------------------+
 237
 238Notes:
 239
 240(1)
 241   This is exact, but may overflow.
 242
 243(2)
 244   This is exact, and cannot overflow.
 245
 246(3)
 247   Division by 0 raises :exc:`ZeroDivisionError`.
 248
 249(4)
 250   -*timedelta.max* is not representable as a :class:`timedelta` object.
 251
 252In addition to the operations listed above :class:`timedelta` objects support
 253certain additions and subtractions with :class:`date` and :class:`datetime`
 254objects (see below).
 255
 256Comparisons of :class:`timedelta` objects are supported with the
 257:class:`timedelta` object representing the smaller duration considered to be the
 258smaller timedelta. In order to stop mixed-type comparisons from falling back to
 259the default comparison by object address, when a :class:`timedelta` object is
 260compared to an object of a different type, :exc:`TypeError` is raised unless the
 261comparison is ``==`` or ``!=``.  The latter cases return :const:`False` or
 262:const:`True`, respectively.
 263
 264:class:`timedelta` objects are :term:`hashable` (usable as dictionary keys), support
 265efficient pickling, and in Boolean contexts, a :class:`timedelta` object is
 266considered to be true if and only if it isn't equal to ``timedelta(0)``.
 267
 268Example usage:
 269
 270    >>> from datetime import timedelta
 271    >>> year = timedelta(days=365)
 272    >>> another_year = timedelta(weeks=40, days=84, hours=23,
 273    ...                          minutes=50, seconds=600)  # adds up to 365 days
 274    >>> year == another_year
 275    True
 276    >>> ten_years = 10 * year
 277    >>> ten_years, ten_years.days // 365
 278    (datetime.timedelta(3650), 10)
 279    >>> nine_years = ten_years - year
 280    >>> nine_years, nine_years.days // 365
 281    (datetime.timedelta(3285), 9)
 282    >>> three_years = nine_years // 3;
 283    >>> three_years, three_years.days // 365
 284    (datetime.timedelta(1095), 3)
 285    >>> abs(three_years - ten_years) == 2 * three_years + year
 286    True
 287
 288
 289.. _datetime-date:
 290
 291:class:`date` Objects
 292---------------------
 293
 294A :class:`date` object represents a date (year, month and day) in an idealized
 295calendar, the current Gregorian calendar indefinitely extended in both
 296directions.  January 1 of year 1 is called day number 1, January 2 of year 1 is
 297called day number 2, and so on.  This matches the definition of the "proleptic
 298Gregorian" calendar in Dershowitz and Reingold's book Calendrical Calculations,
 299where it's the base calendar for all computations.  See the book for algorithms
 300for converting between proleptic Gregorian ordinals and many other calendar
 301systems.
 302
 303
 304.. class:: date(year, month, day)
 305
 306   All arguments are required.  Arguments may be ints or longs, in the following
 307   ranges:
 308
 309   * ``MINYEAR <= year <= MAXYEAR``
 310   * ``1 <= month <= 12``
 311   * ``1 <= day <= number of days in the given month and year``
 312
 313   If an argument outside those ranges is given, :exc:`ValueError` is raised.
 314
 315Other constructors, all class methods:
 316
 317
 318.. method:: date.today()
 319
 320   Return the current local date.  This is equivalent to
 321   ``date.fromtimestamp(time.time())``.
 322
 323
 324.. method:: date.fromtimestamp(timestamp)
 325
 326   Return the local date corresponding to the POSIX timestamp, such as is returned
 327   by :func:`time.time`.  This may raise :exc:`ValueError`, if the timestamp is out
 328   of the range of values supported by the platform C :cfunc:`localtime` function.
 329   It's common for this to be restricted to years from 1970 through 2038.  Note
 330   that on non-POSIX systems that include leap seconds in their notion of a
 331   timestamp, leap seconds are ignored by :meth:`fromtimestamp`.
 332
 333
 334.. method:: date.fromordinal(ordinal)
 335
 336   Return the date corresponding to the proleptic Gregorian ordinal, where January
 337   1 of year 1 has ordinal 1.  :exc:`ValueError` is raised unless ``1 <= ordinal <=
 338   date.max.toordinal()``. For any date *d*, ``date.fromordinal(d.toordinal()) ==
 339   d``.
 340
 341Class attributes:
 342
 343
 344.. attribute:: date.min
 345
 346   The earliest representable date, ``date(MINYEAR, 1, 1)``.
 347
 348
 349.. attribute:: date.max
 350
 351   The latest representable date, ``date(MAXYEAR, 12, 31)``.
 352
 353
 354.. attribute:: date.resolution
 355
 356   The smallest possible difference between non-equal date objects,
 357   ``timedelta(days=1)``.
 358
 359Instance attributes (read-only):
 360
 361
 362.. attribute:: date.year
 363
 364   Between :const:`MINYEAR` and :const:`MAXYEAR` inclusive.
 365
 366
 367.. attribute:: date.month
 368
 369   Between 1 and 12 inclusive.
 370
 371
 372.. attribute:: date.day
 373
 374   Between 1 and the number of days in the given month of the given year.
 375
 376Supported operations:
 377
 378+-------------------------------+----------------------------------------------+
 379| Operation                     | Result                                       |
 380+===============================+==============================================+
 381| ``date2 = date1 + timedelta`` | *date2* is ``timedelta.days`` days removed   |
 382|                               | from *date1*.  (1)                           |
 383+-------------------------------+----------------------------------------------+
 384| ``date2 = date1 - timedelta`` | Computes *date2* such that ``date2 +         |
 385|                               | timedelta == date1``. (2)                    |
 386+-------------------------------+----------------------------------------------+
 387| ``timedelta = date1 - date2`` | \(3)                                         |
 388+-------------------------------+----------------------------------------------+
 389| ``date1 < date2``             | *date1* is considered less than *date2* when |
 390|                               | *date1* precedes *date2* in time. (4)        |
 391+-------------------------------+----------------------------------------------+
 392
 393Notes:
 394
 395(1)
 396   *date2* is moved forward in time if ``timedelta.days > 0``, or backward if
 397   ``timedelta.days < 0``.  Afterward ``date2 - date1 == timedelta.days``.
 398   ``timedelta.seconds`` and ``timedelta.microseconds`` are ignored.
 399   :exc:`OverflowError` is raised if ``date2.year`` would be smaller than
 400   :const:`MINYEAR` or larger than :const:`MAXYEAR`.
 401
 402(2)
 403   This isn't quite equivalent to date1 + (-timedelta), because -timedelta in
 404   isolation can overflow in cases where date1 - timedelta does not.
 405   ``timedelta.seconds`` and ``timedelta.microseconds`` are ignored.
 406
 407(3)
 408   This is exact, and cannot overflow.  timedelta.seconds and
 409   timedelta.microseconds are 0, and date2 + timedelta == date1 after.
 410
 411(4)
 412   In other words, ``date1 < date2`` if and only if ``date1.toordinal() <
 413   date2.toordinal()``. In order to stop comparison from falling back to the
 414   default scheme of comparing object addresses, date comparison normally raises
 415   :exc:`TypeError` if the other comparand isn't also a :class:`date` object.
 416   However, ``NotImplemented`` is returned instead if the other comparand has a
 417   :meth:`timetuple` attribute.  This hook gives other kinds of date objects a
 418   chance at implementing mixed-type comparison. If not, when a :class:`date`
 419   object is compared to an object of a different type, :exc:`TypeError` is raised
 420   unless the comparison is ``==`` or ``!=``.  The latter cases return
 421   :const:`False` or :const:`True`, respectively.
 422
 423Dates can be used as dictionary keys. In Boolean contexts, all :class:`date`
 424objects are considered to be true.
 425
 426Instance methods:
 427
 428
 429.. method:: date.replace(year, month, day)
 430
 431   Return a date with the same value, except for those members given new values by
 432   whichever keyword arguments are specified.  For example, if ``d == date(2002,
 433   12, 31)``, then ``d.replace(day=26) == date(2002, 12, 26)``.
 434
 435
 436.. method:: date.timetuple()
 437
 438   Return a :class:`time.struct_time` such as returned by :func:`time.localtime`.
 439   The hours, minutes and seconds are 0, and the DST flag is -1. ``d.timetuple()``
 440   is equivalent to ``time.struct_time((d.year, d.month, d.day, 0, 0, 0,
 441   d.weekday(), d.toordinal() - date(d.year, 1, 1).toordinal() + 1, -1))``
 442
 443
 444.. method:: date.toordinal()
 445
 446   Return the proleptic Gregorian ordinal of the date, where January 1 of year 1
 447   has ordinal 1.  For any :class:`date` object *d*,
 448   ``date.fromordinal(d.toordinal()) == d``.
 449
 450
 451.. method:: date.weekday()
 452
 453   Return the day of the week as an integer, where Monday is 0 and Sunday is 6.
 454   For example, ``date(2002, 12, 4).weekday() == 2``, a Wednesday. See also
 455   :meth:`isoweekday`.
 456
 457
 458.. method:: date.isoweekday()
 459
 460   Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
 461   For example, ``date(2002, 12, 4).isoweekday() == 3``, a Wednesday. See also
 462   :meth:`weekday`, :meth:`isocalendar`.
 463
 464
 465.. method:: date.isocalendar()
 466
 467   Return a 3-tuple, (ISO year, ISO week number, ISO weekday).
 468
 469   The ISO calendar is a widely used variant of the Gregorian calendar. See
 470   http://www.phys.uu.nl/ vgent/calendar/isocalendar.htm for a good explanation.
 471
 472   The ISO year consists of 52 or 53 full weeks, and where a week starts on a
 473   Monday and ends on a Sunday.  The first week of an ISO year is the first
 474   (Gregorian) calendar week of a year containing a Thursday. This is called week
 475   number 1, and the ISO year of that Thursday is the same as its Gregorian year.
 476
 477   For example, 2004 begins on a Thursday, so the first week of ISO year 2004
 478   begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan 2004, so that
 479   ``date(2003, 12, 29).isocalendar() == (2004, 1, 1)`` and ``date(2004, 1,
 480   4).isocalendar() == (2004, 1, 7)``.
 481
 482
 483.. method:: date.isoformat()
 484
 485   Return a string representing the date in ISO 8601 format, 'YYYY-MM-DD'.  For
 486   example, ``date(2002, 12, 4).isoformat() == '2002-12-04'``.
 487
 488
 489.. method:: date.__str__()
 490
 491   For a date *d*, ``str(d)`` is equivalent to ``d.isoformat()``.
 492
 493
 494.. method:: date.ctime()
 495
 496   Return a string representing the date, for example ``date(2002, 12,
 497   4).ctime() == 'Wed Dec 4 00:00:00 2002'``. ``d.ctime()`` is equivalent to
 498   ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the native C
 499   :cfunc:`ctime` function (which :func:`time.ctime` invokes, but which
 500   :meth:`date.ctime` does not invoke) conforms to the C standard.
 501
 502
 503.. method:: date.strftime(format)
 504
 505   Return a string representing the date, controlled by an explicit format string.
 506   Format codes referring to hours, minutes or seconds will see 0 values. See
 507   section :ref:`strftime-behavior`.
 508
 509Example of counting days to an event::
 510
 511    >>> import time
 512    >>> from datetime import date
 513    >>> today = date.today()
 514    >>> today
 515    datetime.date(2007, 12, 5)
 516    >>> today == date.fromtimestamp(time.time())
 517    True
 518    >>> my_birthday = date(today.year, 6, 24)
 519    >>> if my_birthday < today:
 520    ...     my_birthday = my_birthday.replace(year=today.year + 1)
 521    >>> my_birthday
 522    datetime.date(2008, 6, 24)
 523    >>> time_to_birthday = abs(my_birthday - today)
 524    >>> time_to_birthday.days
 525    202
 526
 527Example of working with :class:`date`:
 528
 529.. doctest::
 530
 531    >>> from datetime import date
 532    >>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
 533    >>> d
 534    datetime.date(2002, 3, 11)
 535    >>> t = d.timetuple()
 536    >>> for i in t:     # doctest: +SKIP
 537    ...     print i
 538    2002                # year
 539    3                   # month
 540    11                  # day
 541    0
 542    0
 543    0
 544    0                   # weekday (0 = Monday)
 545    70                  # 70th day in the year
 546    -1
 547    >>> ic = d.isocalendar()
 548    >>> for i in ic:    # doctest: +SKIP
 549    ...     print i
 550    2002                # ISO year
 551    11                  # ISO week number
 552    1                   # ISO day number ( 1 = Monday )
 553    >>> d.isoformat()
 554    '2002-03-11'
 555    >>> d.strftime("%d/%m/%y")
 556    '11/03/02'
 557    >>> d.strftime("%A %d. %B %Y")
 558    'Monday 11. March 2002'
 559
 560
 561.. _datetime-datetime:
 562
 563:class:`datetime` Objects
 564-------------------------
 565
 566A :class:`datetime` object is a single object containing all the information
 567from a :class:`date` object and a :class:`time` object.  Like a :class:`date`
 568object, :class:`datetime` assumes the current Gregorian calendar extended in
 569both directions; like a time object, :class:`datetime` assumes there are exactly
 5703600\*24 seconds in every day.
 571
 572Constructor:
 573
 574
 575.. class:: datetime(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])
 576
 577   The year, month and day arguments are required.  *tzinfo* may be ``None``, or an
 578   instance of a :class:`tzinfo` subclass.  The remaining arguments may be ints or
 579   longs, in the following ranges:
 580
 581   * ``MINYEAR <= year <= MAXYEAR``
 582   * ``1 <= month <= 12``
 583   * ``1 <= day <= number of days in the given month and year``
 584   * ``0 <= hour < 24``
 585   * ``0 <= minute < 60``
 586   * ``0 <= second < 60``
 587   * ``0 <= microsecond < 1000000``
 588
 589   If an argument outside those ranges is given, :exc:`ValueError` is raised.
 590
 591Other constructors, all class methods:
 592
 593
 594.. method:: datetime.today()
 595
 596   Return the current local datetime, with :attr:`tzinfo` ``None``. This is
 597   equivalent to ``datetime.fromtimestamp(time.time())``. See also :meth:`now`,
 598   :meth:`fromtimestamp`.
 599
 600
 601.. method:: datetime.now([tz])
 602
 603   Return the current local date and time.  If optional argument *tz* is ``None``
 604   or not specified, this is like :meth:`today`, but, if possible, supplies more
 605   precision than can be gotten from going through a :func:`time.time` timestamp
 606   (for example, this may be possible on platforms supplying the C
 607   :cfunc:`gettimeofday` function).
 608
 609   Else *tz* must be an instance of a class :class:`tzinfo` subclass, and the
 610   current date and time are converted to *tz*'s time zone.  In this case the
 611   result is equivalent to ``tz.fromutc(datetime.utcnow().replace(tzinfo=tz))``.
 612   See also :meth:`today`, :meth:`utcnow`.
 613
 614
 615.. method:: datetime.utcnow()
 616
 617   Return the current UTC date and time, with :attr:`tzinfo` ``None``. This is like
 618   :meth:`now`, but returns the current UTC date and time, as a naive
 619   :class:`datetime` object. See also :meth:`now`.
 620
 621
 622.. method:: datetime.fromtimestamp(timestamp[, tz])
 623
 624   Return the local date and time corresponding to the POSIX timestamp, such as is
 625   returned by :func:`time.time`. If optional argument *tz* is ``None`` or not
 626   specified, the timestamp is converted to the platform's local date and time, and
 627   the returned :class:`datetime` object is naive.
 628
 629   Else *tz* must be an instance of a class :class:`tzinfo` subclass, and the
 630   timestamp is converted to *tz*'s time zone.  In this case the result is
 631   equivalent to
 632   ``tz.fromutc(datetime.utcfromtimestamp(timestamp).replace(tzinfo=tz))``.
 633
 634   :meth:`fromtimestamp` may raise :exc:`ValueError`, if the timestamp is out of
 635   the range of values supported by the platform C :cfunc:`localtime` or
 636   :cfunc:`gmtime` functions.  It's common for this to be restricted to years in
 637   1970 through 2038. Note that on non-POSIX systems that include leap seconds in
 638   their notion of a timestamp, leap seconds are ignored by :meth:`fromtimestamp`,
 639   and then it's possible to have two timestamps differing by a second that yield
 640   identical :class:`datetime` objects. See also :meth:`utcfromtimestamp`.
 641
 642
 643.. method:: datetime.utcfromtimestamp(timestamp)
 644
 645   Return the UTC :class:`datetime` corresponding to the POSIX timestamp, with
 646   :attr:`tzinfo` ``None``. This may raise :exc:`ValueError`, if the timestamp is
 647   out of the range of values supported by the platform C :cfunc:`gmtime` function.
 648   It's common for this to be restricted to years in 1970 through 2038. See also
 649   :meth:`fromtimestamp`.
 650
 651
 652.. method:: datetime.fromordinal(ordinal)
 653
 654   Return the :class:`datetime` corresponding to the proleptic Gregorian ordinal,
 655   where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1
 656   <= ordinal <= datetime.max.toordinal()``.  The hour, minute, second and
 657   microsecond of the result are all 0, and :attr:`tzinfo` is ``None``.
 658
 659
 660.. method:: datetime.combine(date, time)
 661
 662   Return a new :class:`datetime` object whose date members are equal to the given
 663   :class:`date` object's, and whose time and :attr:`tzinfo` members are equal to
 664   the given :class:`time` object's. For any :class:`datetime` object *d*, ``d ==
 665   datetime.combine(d.date(), d.timetz())``.  If date is a :class:`datetime`
 666   object, its time and :attr:`tzinfo` members are ignored.
 667
 668
 669.. method:: datetime.strptime(date_string, format)
 670
 671   Return a :class:`datetime` corresponding to *date_string*, parsed according to
 672   *format*.  This is equivalent to ``datetime(*(time.strptime(date_string,
 673   format)[0:6]))``. :exc:`ValueError` is raised if the date_string and format
 674   can't be parsed by :func:`time.strptime` or if it returns a value which isn't a
 675   time tuple.
 676
 677   .. versionadded:: 2.5
 678
 679Class attributes:
 680
 681
 682.. attribute:: datetime.min
 683
 684   The earliest representable :class:`datetime`, ``datetime(MINYEAR, 1, 1,
 685   tzinfo=None)``.
 686
 687
 688.. attribute:: datetime.max
 689
 690   The latest representable :class:`datetime`, ``datetime(MAXYEAR, 12, 31, 23, 59,
 691   59, 999999, tzinfo=None)``.
 692
 693
 694.. attribute:: datetime.resolution
 695
 696   The smallest possible difference between non-equal :class:`datetime` objects,
 697   ``timedelta(microseconds=1)``.
 698
 699Instance attributes (read-only):
 700
 701
 702.. attribute:: datetime.year
 703
 704   Between :const:`MINYEAR` and :const:`MAXYEAR` inclusive.
 705
 706
 707.. attribute:: datetime.month
 708
 709   Between 1 and 12 inclusive.
 710
 711
 712.. attribute:: datetime.day
 713
 714   Between 1 and the number of days in the given month of the given year.
 715
 716
 717.. attribute:: datetime.hour
 718
 719   In ``range(24)``.
 720
 721
 722.. attribute:: datetime.minute
 723
 724   In ``range(60)``.
 725
 726
 727.. attribute:: datetime.second
 728
 729   In ``range(60)``.
 730
 731
 732.. attribute:: datetime.microsecond
 733
 734   In ``range(1000000)``.
 735
 736
 737.. attribute:: datetime.tzinfo
 738
 739   The object passed as the *tzinfo* argument to the :class:`datetime` constructor,
 740   or ``None`` if none was passed.
 741
 742Supported operations:
 743
 744+---------------------------------------+-------------------------------+
 745| Operation                             | Result                        |
 746+=======================================+===============================+
 747| ``datetime2 = datetime1 + timedelta`` | \(1)                          |
 748+---------------------------------------+-------------------------------+
 749| ``datetime2 = datetime1 - timedelta`` | \(2)                          |
 750+---------------------------------------+-------------------------------+
 751| ``timedelta = datetime1 - datetime2`` | \(3)                          |
 752+---------------------------------------+-------------------------------+
 753| ``datetime1 < datetime2``             | Compares :class:`datetime` to |
 754|                                       | :class:`datetime`. (4)        |
 755+---------------------------------------+-------------------------------+
 756
 757(1)
 758   datetime2 is a duration of timedelta removed from datetime1, moving forward in
 759   time if ``timedelta.days`` > 0, or backward if ``timedelta.days`` < 0.  The
 760   result has the same :attr:`tzinfo` member as the input datetime, and datetime2 -
 761   datetime1 == timedelta after. :exc:`OverflowError` is raised if datetime2.year
 762   would be smaller than :const:`MINYEAR` or larger than :const:`MAXYEAR`. Note
 763   that no time zone adjustments are done even if the input is an aware object.
 764
 765(2)
 766   Computes the datetime2 such that datetime2 + timedelta == datetime1. As for
 767   addition, the result has the same :attr:`tzinfo` member as the input datetime,
 768   and no time zone adjustments are done even if the input is aware. This isn't
 769   quite equivalent to datetime1 + (-timedelta), because -timedelta in isolation
 770   can overflow in cases where datetime1 - timedelta does not.
 771
 772(3)
 773   Subtraction of a :class:`datetime` from a :class:`datetime` is defined only if
 774   both operands are naive, or if both are aware.  If one is aware and the other is
 775   naive, :exc:`TypeError` is raised.
 776
 777   If both are naive, or both are aware and have the same :attr:`tzinfo` member,
 778   the :attr:`tzinfo` members are ignored, and the result is a :class:`timedelta`
 779   object *t* such that ``datetime2 + t == datetime1``.  No time zone adjustments
 780   are done in this case.
 781
 782   If both are aware and have different :attr:`tzinfo` members, ``a-b`` acts as if
 783   *a* and *b* were first converted to naive UTC datetimes first.  The result is
 784   ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) -
 785   b.utcoffset())`` except that the implementation never overflows.
 786
 787(4)
 788   *datetime1* is considered less than *datetime2* when *datetime1* precedes
 789   *datetime2* in time.
 790
 791   If one comparand is naive and the other is aware, :exc:`TypeError` is raised.
 792   If both comparands are aware, and have the same :attr:`tzinfo` member, the
 793   common :attr:`tzinfo` member is ignored and the base datetimes are compared.  If
 794   both comparands are aware and have different :attr:`tzinfo` members, the
 795   comparands are first adjusted by subtracting their UTC offsets (obtained from
 796   ``self.utcoffset()``).
 797
 798   .. note::
 799
 800      In order to stop comparison from falling back to the default scheme of comparing
 801      object addresses, datetime comparison normally raises :exc:`TypeError` if the
 802      other comparand isn't also a :class:`datetime` object.  However,
 803      ``NotImplemented`` is returned instead if the other comparand has a
 804      :meth:`timetuple` attribute.  This hook gives other kinds of date objects a
 805      chance at implementing mixed-type comparison.  If not, when a :class:`datetime`
 806      object is compared to an object of a different type, :exc:`TypeError` is raised
 807      unless the comparison is ``==`` or ``!=``.  The latter cases return
 808      :const:`False` or :const:`True`, respectively.
 809
 810:class:`datetime` objects can be used as dictionary keys. In Boolean contexts,
 811all :class:`datetime` objects are considered to be true.
 812
 813Instance methods:
 814
 815
 816.. method:: datetime.date()
 817
 818   Return :class:`date` object with same year, month and day.
 819
 820
 821.. method:: datetime.time()
 822
 823   Return :class:`time` object with same hour, minute, second and microsecond.
 824   :attr:`tzinfo` is ``None``.  See also method :meth:`timetz`.
 825
 826
 827.. method:: datetime.timetz()
 828
 829   Return :class:`time` object with same hour, minute, second, microsecond, and
 830   tzinfo members.  See also method :meth:`time`.
 831
 832
 833.. method:: datetime.replace([year[, month[, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]]]]])
 834
 835   Return a datetime with the same members, except for those members given new
 836   values by whichever keyword arguments are specified.  Note that ``tzinfo=None``
 837   can be specified to create a naive datetime from an aware datetime with no
 838   conversion of date and time members.
 839
 840
 841.. method:: datetime.astimezone(tz)
 842
 843   Return a :class:`datetime` object with new :attr:`tzinfo` member *tz*, adjusting
 844   the date and time members so the result is the same UTC time as *self*, but in
 845   *tz*'s local time.
 846
 847   *tz* must be an instance of a :class:`tzinfo` subclass, and its
 848   :meth:`utcoffset` and :meth:`dst` methods must not return ``None``.  *self* must
 849   be aware (``self.tzinfo`` must not be ``None``, and ``self.utcoffset()`` must
 850   not return ``None``).
 851
 852   If ``self.tzinfo`` is *tz*, ``self.astimezone(tz)`` is equal to *self*:  no
 853   adjustment of date or time members is performed. Else the result is local time
 854   in time zone *tz*, representing the same UTC time as *self*:  after ``astz =
 855   dt.astimezone(tz)``, ``astz - astz.utcoffset()`` will usually have the same date
 856   and time members as ``dt - dt.utcoffset()``. The discussion of class
 857   :class:`tzinfo` explains the cases at Daylight Saving Time transition boundaries
 858   where this cannot be achieved (an issue only if *tz* models both standard and
 859   daylight time).
 860
 861   If you merely want to attach a time zone object *tz* to a datetime *dt* without
 862   adjustment of date and time members, use ``dt.replace(tzinfo=tz)``.  If you
 863   merely want to remove the time zone object from an aware datetime *dt* without
 864   conversion of date and time members, use ``dt.replace(tzinfo=None)``.
 865
 866   Note that the default :meth:`tzinfo.fromutc` method can be overridden in a
 867   :class:`tzinfo` subclass to affect the result returned by :meth:`astimezone`.
 868   Ignoring error cases, :meth:`astimezone` acts like::
 869
 870      def astimezone(self, tz):
 871          if self.tzinfo is tz:
 872              return self
 873          # Convert self to UTC, and attach the new time zone object.
 874          utc = (self - self.utcoffset()).replace(tzinfo=tz)
 875          # Convert from UTC to tz's local time.
 876          return tz.fromutc(utc)
 877
 878
 879.. method:: datetime.utcoffset()
 880
 881   If :attr:`tzinfo` is ``None``, returns ``None``, else returns
 882   ``self.tzinfo.utcoffset(self)``, and raises an exception if the latter doesn't
 883   return ``None``, or a :class:`timedelta` object representing a whole number of
 884   minutes with magnitude less than one day.
 885
 886
 887.. method:: datetime.dst()
 888
 889   If :attr:`tzinfo` is ``None``, returns ``None``, else returns
 890   ``self.tzinfo.dst(self)``, and raises an exception if the latter doesn't return
 891   ``None``, or a :class:`timedelta` object representing a whole number of minutes
 892   with magnitude less than one day.
 893
 894
 895.. method:: datetime.tzname()
 896
 897   If :attr:`tzinfo` is ``None``, returns ``None``, else returns
 898   ``self.tzinfo.tzname(self)``, raises an exception if the latter doesn't return
 899   ``None`` or a string object,
 900
 901
 902.. method:: datetime.timetuple()
 903
 904   Return a :class:`time.struct_time` such as returned by :func:`time.localtime`.
 905   ``d.timetuple()`` is equivalent to ``time.struct_time((d.year, d.month, d.day,
 906   d.hour, d.minute, d.second, d.weekday(), d.toordinal() - date(d.year, 1,
 907   1).toordinal() + 1, dst))`` The :attr:`tm_isdst` flag of the result is set
 908   according to the :meth:`dst` method:  :attr:`tzinfo` is ``None`` or :meth:`dst`
 909   returns ``None``, :attr:`tm_isdst` is set to  ``-1``; else if :meth:`dst`
 910   returns a non-zero value, :attr:`tm_isdst` is set to ``1``; else ``tm_isdst`` is
 911   set to ``0``.
 912
 913
 914.. method:: datetime.utctimetuple()
 915
 916   If :class:`datetime` instance *d* is naive, this is the same as
 917   ``d.timetuple()`` except that :attr:`tm_isdst` is forced to 0 regardless of what
 918   ``d.dst()`` returns.  DST is never in effect for a UTC time.
 919
 920   If *d* is aware, *d* is normalized to UTC time, by subtracting
 921   ``d.utcoffset()``, and a :class:`time.struct_time` for the normalized time is
 922   returned.  :attr:`tm_isdst` is forced to 0. Note that the result's
 923   :attr:`tm_year` member may be :const:`MINYEAR`\ -1 or :const:`MAXYEAR`\ +1, if
 924   *d*.year was ``MINYEAR`` or ``MAXYEAR`` and UTC adjustment spills over a year
 925   boundary.
 926
 927
 928.. method:: datetime.toordinal()
 929
 930   Return the proleptic Gregorian ordinal of the date.  The same as
 931   ``self.date().toordinal()``.
 932
 933
 934.. method:: datetime.weekday()
 935
 936   Return the day of the week as an integer, where Monday is 0 and Sunday is 6.
 937   The same as ``self.date().weekday()``. See also :meth:`isoweekday`.
 938
 939
 940.. method:: datetime.isoweekday()
 941
 942   Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
 943   The same as ``self.date().isoweekday()``. See also :meth:`weekday`,
 944   :meth:`isocalendar`.
 945
 946
 947.. method:: datetime.isocalendar()
 948
 949   Return a 3-tuple, (ISO year, ISO week number, ISO weekday).  The same as
 950   ``self.date().isocalendar()``.
 951
 952
 953.. method:: datetime.isoformat([sep])
 954
 955   Return a string representing the date and time in ISO 8601 format,
 956   YYYY-MM-DDTHH:MM:SS.mmmmmm or, if :attr:`microsecond` is 0,
 957   YYYY-MM-DDTHH:MM:SS
 958
 959   If :meth:`utcoffset` does not return ``None``, a 6-character string is
 960   appended, giving the UTC offset in (signed) hours and minutes:
 961   YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM or, if :attr:`microsecond` is 0
 962   YYYY-MM-DDTHH:MM:SS+HH:MM
 963
 964   The optional argument *sep* (default ``'T'``) is a one-character separator,
 965   placed between the date and time portions of the result.  For example,
 966
 967      >>> from datetime import tzinfo, timedelta, datetime
 968      >>> class TZ(tzinfo):
 969      ...     def utcoffset(self, dt): return timedelta(minutes=-399)
 970      ...
 971      >>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
 972      '2002-12-25 00:00:00-06:39'
 973
 974
 975.. method:: datetime.__str__()
 976
 977   For a :class:`datetime` instance *d*, ``str(d)`` is equivalent to
 978   ``d.isoformat(' ')``.
 979
 980
 981.. method:: datetime.ctime()
 982
 983   Return a string representing the date and time, for example ``datetime(2002, 12,
 984   4, 20, 30, 40).ctime() == 'Wed Dec  4 20:30:40 2002'``. ``d.ctime()`` is
 985   equivalent to ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the
 986   native C :cfunc:`ctime` function (which :func:`time.ctime` invokes, but which
 987   :meth:`datetime.ctime` does not invoke) conforms to the C standard.
 988
 989
 990.. method:: datetime.strftime(format)
 991
 992   Return a string representing the date and time, controlled by an explicit format
 993   string.  See section :ref:`strftime-behavior`.
 994
 995Examples of working with datetime objects:
 996
 997.. doctest::
 998
 999    >>> from datetime import datetime, date, time
1000    >>> # Using datetime.combine()
1001    >>> d = date(2005, 7, 14)
1002    >>> t = time(12, 30)
1003    >>> datetime.combine(d, t)
1004    datetime.datetime(2005, 7, 14, 12, 30)
1005    >>> # Using datetime.now() or datetime.utcnow()
1006    >>> datetime.now()   # doctest: +SKIP
1007    datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
1008    >>> datetime.utcnow()   # doctest: +SKIP
1009    datetime.datetime(2007, 12, 6, 15, 29, 43, 79060)
1010    >>> # Using datetime.strptime()
1011    >>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
1012    >>> dt
1013    datetime.datetime(2006, 11, 21, 16, 30)
1014    >>> # Using datetime.timetuple() to get tuple of all attributes
1015    >>> tt = dt.timetuple()
1016    >>> for it in tt:   # doctest: +SKIP
1017    ...     print it
1018    ...
1019    2006    # year
1020    11      # month
1021    21      # day
1022    16      # hour
1023    30      # minute
1024    0       # second
1025    1       # weekday (0 = Monday)
1026    325     # number of days since 1st January
1027    -1      # dst - method tzinfo.dst() returned None
1028    >>> # Date in ISO format
1029    >>> ic = dt.isocalendar()
1030    >>> for it in ic:   # doctest: +SKIP
1031    ...     print it
1032    ...
1033    2006    # ISO year
1034    47      # ISO week
1035    2       # ISO weekday
1036    >>> # Formatting datetime
1037    >>> dt.strftime("%A, %d. %B %Y %I:%M%p")
1038    'Tuesday, 21. November 2006 04:30PM'
1039
1040Using datetime with tzinfo:
1041
1042    >>> from datetime import timedelta, datetime, tzinfo
1043    >>> class GMT1(tzinfo):
1044    ...     def __init__(self):         # DST starts last Sunday in March
1045    ...         d = datetime(dt.year, 4, 1)   # ends last Sunday in October
1046    ...         self.dston = d - timedelta(days=d.weekday() + 1)
1047    ...         d = datetime(dt.year, 11, 1)
1048    ...         self.dstoff = d - timedelta(days=d.weekday() + 1)
1049    ...     def utcoffset(self, dt):
1050    ...         return timedelta(hours=1) + self.dst(dt)
1051    ...     def dst(self, dt):
1052    ...         if self.dston <=  dt.replace(tzinfo=None) < self.dstoff:
1053    ...             return timedelta(hours=1)
1054    ...         else:
1055    ...             return timedelta(0)
1056    ...     def tzname(self,dt):
1057    ...          return "GMT +1"
1058    ...
1059    >>> class GMT2(tzinfo):
1060    ...     def __init__(self):
1061    ...         d = datetime(dt.year, 4, 1)
1062    ...         self.dston = d - timedelta(days=d.weekday() + 1)
1063    ...         d = datetime(dt.year, 11, 1)
1064    ...         self.dstoff = d - timedelta(days=d.weekday() + 1)
1065    ...     def utcoffset(self, dt):
1066    ...         return timedelta(hours=1) + self.dst(dt)
1067    ...     def dst(self, dt):
1068    ...         if self.dston <=  dt.replace(tzinfo=None) < self.dstoff:
1069    ...             return timedelta(hours=2)
1070    ...         else:
1071    ...             return timedelta(0)
1072    ...     def tzname(self,dt):
1073    ...         return "GMT +2"
1074    ...
1075    >>> gmt1 = GMT1()
1076    >>> # Daylight Saving Time
1077    >>> dt1 = datetime(2006, 11, 21, 16, 30, tzinfo=gmt1)
1078    >>> dt1.dst()
1079    datetime.timedelta(0)
1080    >>> dt1.utcoffset()
1081    datetime.timedelta(0, 3600)
1082    >>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=gmt1)
1083    >>> dt2.dst()
1084    datetime.timedelta(0, 3600)
1085    >>> dt2.utcoffset()
1086    datetime.timedelta(0, 7200)
1087    >>> # Convert datetime to another time zone
1088    >>> dt3 = dt2.astimezone(GMT2())
1089    >>> dt3     # doctest: +ELLIPSIS
1090    datetime.datetime(2006, 6, 14, 14, 0, tzinfo=<GMT2 object at 0x...>)
1091    >>> dt2     # doctest: +ELLIPSIS
1092    datetime.datetime(2006, 6, 14, 13, 0, tzinfo=<GMT1 object at 0x...>)
1093    >>> dt2.utctimetuple() == dt3.utctimetuple()
1094    True
1095
1096
1097
1098.. _datetime-time:
1099
1100:class:`time` Objects
1101---------------------
1102
1103A time object represents a (local) time of day, independent of any particular
1104day, and subject to adjustment via a :class:`tzinfo` object.
1105
1106
1107.. class:: time(hour[, minute[, second[, microsecond[, tzinfo]]]])
1108
1109   All arguments are optional.  *tzinfo* may be ``None``, or an instance of a
1110   :class:`tzinfo` subclass.  The remaining arguments may be ints or longs, in the
1111   following ranges:
1112
1113   * ``0 <= hour < 24``
1114   * ``0 <= minute < 60``
1115   * ``0 <= second < 60``
1116   * ``0 <= microsecond < 1000000``.
1117
1118   If an argument outside those ranges is given, :exc:`ValueError` is raised.  All
1119   default to ``0`` except *tzinfo*, which defaults to :const:`None`.
1120
1121Class attributes:
1122
1123
1124.. attribute:: time.min
1125
1126   The earliest representable :class:`time`, ``time(0, 0, 0, 0)``.
1127
1128
1129.. attribute:: time.max
1130
1131   The latest representable :class:`time`, ``time(23, 59, 59, 999999)``.
1132
1133
1134.. attribute:: time.resolution
1135
1136   The smallest possible difference between non-equal :class:`time` objects,
1137   ``timedelta(microseconds=1)``, although note that arithmetic on :class:`time`
1138   objects is not supported.
1139
1140Instance attributes (read-only):
1141
1142
1143.. attribute:: time.hour
1144
1145   In ``range(24)``.
1146
1147
1148.. attribute:: time.minute
1149
1150   In ``range(60)``.
1151
1152
1153.. attribute:: time.second
1154
1155   In ``range(60)``.
1156
1157
1158.. attribute:: time.microsecond
1159
1160   In ``range(1000000)``.
1161
1162
1163.. attribute:: time.tzinfo
1164
1165   The object passed as the tzinfo argument to the :class:`time` constructor, or
1166   ``None`` if none was passed.
1167
1168Supported operations:
1169
1170* comparison of :class:`time` to :class:`time`, where *a* is considered less
1171  than *b* when *a* precedes *b* in time.  If one comparand is naive and the other
1172  is aware, :exc:`TypeError` is raised.  If both comparands are aware, and have
1173  the same :attr:`tzinfo` member, the common :attr:`tzinfo` member is ignored and
1174  the base times are compared.  If both comparands are aware and have different
1175  :attr:`tzinfo` members, the comparands are first adjusted by subtracting their
1176  UTC offsets (obtained from ``self.utcoffset()``). In order to stop mixed-type
1177  comparisons from falling back to the default comparison by object address, when
1178  a :class:`time` object is compared to an object of a different type,
1179  :exc:`TypeError` is raised unless the comparison is ``==`` or ``!=``.  The
1180  latter cases return :const:`False` or :const:`True`, respectively.
1181
1182* hash, use as dict key
1183
1184* efficient pickling
1185
1186* in Boolean contexts, a :class:`time` object is considered to be true if and
1187  only if, after converting it to minutes and subtracting :meth:`utcoffset` (or
1188  ``0`` if that's ``None``), the result is non-zero.
1189
1190Instance methods:
1191
1192
1193.. method:: time.replace([hour[, minute[, second[, microsecond[, tzinfo]]]]])
1194
1195   Return a :class:`time` with the same value, except for those members given new
1196   values by whichever keyword arguments are specified.  Note that ``tzinfo=None``
1197   can be specified to create a naive :class:`time` from an aware :class:`time`,
1198   without conversion of the time members.
1199
1200
1201.. method:: time.isoformat()
1202
1203   Return a string representing the time in ISO 8601 format, HH:MM:SS.mmmmmm or, if
1204   self.microsecond is 0, HH:MM:SS If :meth:`utcoffset` does not return ``None``, a
1205   6-character string is appended, giving the UTC offset in (signed) hours and
1206   minutes: HH:MM:SS.mmmmmm+HH:MM or, if self.microsecond is 0, HH:MM:SS+HH:MM
1207
1208
1209.. method:: time.__str__()
1210
1211   For a time *t*, ``str(t)`` is equivalent to ``t.isoformat()``.
1212
1213
1214.. method:: time.strftime(format)
1215
1216   Return a string representing the time, controlled by an explicit format string.
1217   See section :ref:`strftime-behavior`.
1218
1219
1220.. method:: time.utcoffset()
1221
1222   If :attr:`tzinfo` is ``None``, returns ``None``, else returns
1223   ``self.tzinfo.utcoffset(None)``, and raises an exception if the latter doesn't
1224   return ``None`` or a :class:`timedelta` object representing a whole number of
1225   minutes with magnitude less than one day.
1226
1227
1228.. method:: time.dst()
1229
1230   If :attr:`tzinfo` is ``None``, returns ``None``, else returns
1231   ``self.tzinfo.dst(None)``, and raises an exception if the latter doesn't return
1232   ``None``, or a :class:`timedelta` object representing a whole number of minutes
1233   with magnitude less than one day.
1234
1235
1236.. method:: time.tzname()
1237
1238   If :attr:`tzinfo` is ``None``, returns ``None``, else returns
1239   ``self.tzinfo.tzname(None)``, or raises an exception if the latter doesn't
1240   return ``None`` or a string object.
1241
1242Example:
1243
1244    >>> from datetime import time, tzinfo
1245    >>> class GMT1(tzinfo):
1246    ...     def utcoffset(self, dt):
1247    ...         return timedelta(hours=1)
1248    ...     def dst(self, dt):
1249    ...         return timedelta(0)
1250    ...     def tzname(self,dt):
1251    ...         return "Europe/Prague"
1252    ...
1253    >>> t = time(12, 10, 30, tzinfo=GMT1())
1254    >>> t                               # doctest: +ELLIPSIS
1255    datetime.time(12, 10, 30, tzinfo=<GMT1 object at 0x...>)
1256    >>> gmt = GMT1()
1257    >>> t.isoformat()
1258    '12:10:30+01:00'
1259    >>> t.dst()
1260    datetime.timedelta(0)
1261    >>> t.tzname()
1262    'Europe/Prague'
1263    >>> t.strftime("%H:%M:%S %Z")
1264    '12:10:30 Europe/Prague'
1265
1266
1267.. _datetime-tzinfo:
1268
1269:class:`tzinfo` Objects
1270-----------------------
1271
1272:class:`tzinfo` is an abstract base class, meaning that this class should not be
1273instantiated directly.  You need to derive a concrete subclass, and (at least)
1274supply implementations of the standard :class:`tzinfo` methods needed by the
1275:class:`datetime` methods you use.  The :mod:`datetime` module does not supply
1276any concrete subclasses of :class:`tzinfo`.
1277
1278An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the
1279constructors for :class:`datetime` and :class:`time` objects. The latter objects
1280view their members as being in local time, and the :class:`tzinfo` object
1281supports methods revealing offset of local time from UTC, the name of the time
1282zone, and DST offset, all relative to a date or time object passed to them.
1283
1284Special requirement for pickling:  A :class:`tzinfo` subclass must have an
1285:meth:`__init__` method that can be called with no arguments, else it can be
1286pickled but possibly not unpickled again.  This is a technical requirement that
1287may be relaxed in the future.
1288
1289A concrete subclass of :class:`tzinfo` may need to implement the following
1290methods.  Exactly which methods are needed depends on the uses made of aware
1291:mod:`datetime` objects.  If in doubt, simply implement all of them.
1292
1293
1294.. method:: tzinfo.utcoffset(self, dt)
1295
1296   Return offset of local time from UTC, in minutes east of UTC.  If local time is
1297   west of UTC, this should be negative.  Note that this is intended to be the
1298   total offset from UTC; for example, if a :class:`tzinfo` object represents both
1299   time zone and DST adjustments, :meth:`utcoffset` should return their sum.  If
1300   the UTC offset isn't known, return ``None``.  Else the value returned must be a
1301   :class:`timedelta` object specifying a whole number of minutes in the range
1302   -1439 to 1439 inclusive (1440 = 24\*60; the magnitude of the offset must be less
1303   than one day).  Most implementations of :meth:`utcoffset` will probably look
1304   like one of these two::
1305
1306      return CONSTANT                 # fixed-offset class
1307      return CONSTANT + self.dst(dt)  # daylight-aware class
1308
1309   If :meth:`utcoffset` does not return ``None``, :meth:`dst` should not return
1310   ``None`` either.
1311
1312   The default implementation of :meth:`utcoffset` raises
1313   :exc:`NotImplementedError`.
1314
1315
1316.. method:: tzinfo.dst(self, dt)
1317
1318   Return the daylight saving time (DST) adjustment, in minutes east of UTC, or
1319   ``None`` if DST information isn't known.  Return ``timedelta(0)`` if DST is not
1320   in effect. If DST is in effect, return the offset as a :class:`timedelta` object
1321   (see :meth:`utcoffset` for details). Note that DST offset, if applicable, has
1322   already been added to the UTC offset returned by :meth:`utcoffset`, so there's
1323   no need to consult :meth:`dst` unless you're interested in obtaining DST info
1324   separately.  For e…

Large files files are truncated, but you can click here to view the full file