1 :mod:`datetime` --- Basic date and time types 2 ============================================= 3 4 .. module:: datetime 5 :synopsis: Basic date and time types. 6 7 .. moduleauthor:: Tim Peters <tim (a] zope.com> 8 .. sectionauthor:: Tim Peters <tim (a] zope.com> 9 .. sectionauthor:: A.M. Kuchling <amk (a] amk.ca> 10 11 **Source code:** :source:`Lib/datetime.py` 12 13 -------------- 14 15 .. XXX what order should the types be discussed in? 16 17 The :mod:`datetime` module supplies classes for manipulating dates and times in 18 both simple and complex ways. While date and time arithmetic is supported, the 19 focus of the implementation is on efficient attribute extraction for output 20 formatting and manipulation. For related functionality, see also the 21 :mod:`time` and :mod:`calendar` modules. 22 23 There are two kinds of date and time objects: "naive" and "aware". 24 25 An aware object has sufficient knowledge of applicable algorithmic and 26 political time adjustments, such as time zone and daylight saving time 27 information, to locate itself relative to other aware objects. An aware object 28 is used to represent a specific moment in time that is not open to 29 interpretation [#]_. 30 31 A naive object does not contain enough information to unambiguously locate 32 itself relative to other date/time objects. Whether a naive object represents 33 Coordinated Universal Time (UTC), local time, or time in some other timezone is 34 purely up to the program, just like it is up to the program whether a 35 particular number represents metres, miles, or mass. Naive objects are easy to 36 understand and to work with, at the cost of ignoring some aspects of reality. 37 38 For applications requiring aware objects, :class:`.datetime` and :class:`.time` 39 objects have an optional time zone information attribute, :attr:`!tzinfo`, that 40 can be set to an instance of a subclass of the abstract :class:`tzinfo` class. 41 These :class:`tzinfo` objects capture information about the offset from UTC 42 time, the time zone name, and whether Daylight Saving Time is in effect. Note 43 that only one concrete :class:`tzinfo` class, the :class:`timezone` class, is 44 supplied by the :mod:`datetime` module. The :class:`timezone` class can 45 represent simple timezones with fixed offset from UTC, such as UTC itself or 46 North American EST and EDT timezones. Supporting timezones at deeper levels of 47 detail is up to the application. The rules for time adjustment across the 48 world are more political than rational, change frequently, and there is no 49 standard suitable for every application aside from UTC. 50 51 The :mod:`datetime` module exports the following constants: 52 53 .. data:: MINYEAR 54 55 The smallest year number allowed in a :class:`date` or :class:`.datetime` object. 56 :const:`MINYEAR` is ``1``. 57 58 59 .. data:: MAXYEAR 60 61 The largest year number allowed in a :class:`date` or :class:`.datetime` object. 62 :const:`MAXYEAR` is ``9999``. 63 64 65 .. seealso:: 66 67 Module :mod:`calendar` 68 General calendar related functions. 69 70 Module :mod:`time` 71 Time access and conversions. 72 73 74 Available Types 75 --------------- 76 77 .. class:: date 78 :noindex: 79 80 An idealized naive date, assuming the current Gregorian calendar always was, and 81 always will be, in effect. Attributes: :attr:`year`, :attr:`month`, and 82 :attr:`day`. 83 84 85 .. class:: time 86 :noindex: 87 88 An idealized time, independent of any particular day, assuming that every day 89 has exactly 24\*60\*60 seconds (there is no notion of "leap seconds" here). 90 Attributes: :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`, 91 and :attr:`.tzinfo`. 92 93 94 .. class:: datetime 95 :noindex: 96 97 A combination of a date and a time. Attributes: :attr:`year`, :attr:`month`, 98 :attr:`day`, :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`, 99 and :attr:`.tzinfo`. 100 101 102 .. class:: timedelta 103 :noindex: 104 105 A duration expressing the difference between two :class:`date`, :class:`.time`, 106 or :class:`.datetime` instances to microsecond resolution. 107 108 109 .. class:: tzinfo 110 :noindex: 111 112 An abstract base class for time zone information objects. These are used by the 113 :class:`.datetime` and :class:`.time` classes to provide a customizable notion of 114 time adjustment (for example, to account for time zone and/or daylight saving 115 time). 116 117 .. class:: timezone 118 :noindex: 119 120 A class that implements the :class:`tzinfo` abstract base class as a 121 fixed offset from the UTC. 122 123 .. versionadded:: 3.2 124 125 126 Objects of these types are immutable. 127 128 Objects of the :class:`date` type are always naive. 129 130 An object of type :class:`.time` or :class:`.datetime` may be naive or aware. 131 A :class:`.datetime` object *d* is aware if ``d.tzinfo`` is not ``None`` and 132 ``d.tzinfo.utcoffset(d)`` does not return ``None``. If ``d.tzinfo`` is 133 ``None``, or if ``d.tzinfo`` is not ``None`` but ``d.tzinfo.utcoffset(d)`` 134 returns ``None``, *d* is naive. A :class:`.time` object *t* is aware 135 if ``t.tzinfo`` is not ``None`` and ``t.tzinfo.utcoffset(None)`` does not return 136 ``None``. Otherwise, *t* is naive. 137 138 The distinction between naive and aware doesn't apply to :class:`timedelta` 139 objects. 140 141 Subclass relationships:: 142 143 object 144 timedelta 145 tzinfo 146 timezone 147 time 148 date 149 datetime 150 151 152 .. _datetime-timedelta: 153 154 :class:`timedelta` Objects 155 -------------------------- 156 157 A :class:`timedelta` object represents a duration, the difference between two 158 dates or times. 159 160 .. class:: timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0) 161 162 All arguments are optional and default to ``0``. Arguments may be integers 163 or floats, and may be positive or negative. 164 165 Only *days*, *seconds* and *microseconds* are stored internally. Arguments are 166 converted to those units: 167 168 * A millisecond is converted to 1000 microseconds. 169 * A minute is converted to 60 seconds. 170 * An hour is converted to 3600 seconds. 171 * A week is converted to 7 days. 172 173 and days, seconds and microseconds are then normalized so that the 174 representation is unique, with 175 176 * ``0 <= microseconds < 1000000`` 177 * ``0 <= seconds < 3600*24`` (the number of seconds in one day) 178 * ``-999999999 <= days <= 999999999`` 179 180 If any argument is a float and there are fractional microseconds, 181 the fractional microseconds left over from all arguments are 182 combined and their sum is rounded to the nearest microsecond using 183 round-half-to-even tiebreaker. If no argument is a float, the 184 conversion and normalization processes are exact (no information is 185 lost). 186 187 If the normalized value of days lies outside the indicated range, 188 :exc:`OverflowError` is raised. 189 190 Note that normalization of negative values may be surprising at first. For 191 example, 192 193 >>> from datetime import timedelta 194 >>> d = timedelta(microseconds=-1) 195 >>> (d.days, d.seconds, d.microseconds) 196 (-1, 86399, 999999) 197 198 199 Class attributes are: 200 201 .. attribute:: timedelta.min 202 203 The most negative :class:`timedelta` object, ``timedelta(-999999999)``. 204 205 206 .. attribute:: timedelta.max 207 208 The most positive :class:`timedelta` object, ``timedelta(days=999999999, 209 hours=23, minutes=59, seconds=59, microseconds=999999)``. 210 211 212 .. attribute:: timedelta.resolution 213 214 The smallest possible difference between non-equal :class:`timedelta` objects, 215 ``timedelta(microseconds=1)``. 216 217 Note that, because of normalization, ``timedelta.max`` > ``-timedelta.min``. 218 ``-timedelta.max`` is not representable as a :class:`timedelta` object. 219 220 Instance attributes (read-only): 221 222 +------------------+--------------------------------------------+ 223 | Attribute | Value | 224 +==================+============================================+ 225 | ``days`` | Between -999999999 and 999999999 inclusive | 226 +------------------+--------------------------------------------+ 227 | ``seconds`` | Between 0 and 86399 inclusive | 228 +------------------+--------------------------------------------+ 229 | ``microseconds`` | Between 0 and 999999 inclusive | 230 +------------------+--------------------------------------------+ 231 232 Supported operations: 233 234 .. XXX this table is too wide! 235 236 +--------------------------------+-----------------------------------------------+ 237 | Operation | Result | 238 +================================+===============================================+ 239 | ``t1 = t2 + t3`` | Sum of *t2* and *t3*. Afterwards *t1*-*t2* == | 240 | | *t3* and *t1*-*t3* == *t2* are true. (1) | 241 +--------------------------------+-----------------------------------------------+ 242 | ``t1 = t2 - t3`` | Difference of *t2* and *t3*. Afterwards *t1* | 243 | | == *t2* - *t3* and *t2* == *t1* + *t3* are | 244 | | true. (1)(6) | 245 +--------------------------------+-----------------------------------------------+ 246 | ``t1 = t2 * i or t1 = i * t2`` | Delta multiplied by an integer. | 247 | | Afterwards *t1* // i == *t2* is true, | 248 | | provided ``i != 0``. | 249 +--------------------------------+-----------------------------------------------+ 250 | | In general, *t1* \* i == *t1* \* (i-1) + *t1* | 251 | | is true. (1) | 252 +--------------------------------+-----------------------------------------------+ 253 | ``t1 = t2 * f or t1 = f * t2`` | Delta multiplied by a float. The result is | 254 | | rounded to the nearest multiple of | 255 | | timedelta.resolution using round-half-to-even.| 256 +--------------------------------+-----------------------------------------------+ 257 | ``f = t2 / t3`` | Division (3) of *t2* by *t3*. Returns a | 258 | | :class:`float` object. | 259 +--------------------------------+-----------------------------------------------+ 260 | ``t1 = t2 / f or t1 = t2 / i`` | Delta divided by a float or an int. The result| 261 | | is rounded to the nearest multiple of | 262 | | timedelta.resolution using round-half-to-even.| 263 +--------------------------------+-----------------------------------------------+ 264 | ``t1 = t2 // i`` or | The floor is computed and the remainder (if | 265 | ``t1 = t2 // t3`` | any) is thrown away. In the second case, an | 266 | | integer is returned. (3) | 267 +--------------------------------+-----------------------------------------------+ 268 | ``t1 = t2 % t3`` | The remainder is computed as a | 269 | | :class:`timedelta` object. (3) | 270 +--------------------------------+-----------------------------------------------+ 271 | ``q, r = divmod(t1, t2)`` | Computes the quotient and the remainder: | 272 | | ``q = t1 // t2`` (3) and ``r = t1 % t2``. | 273 | | q is an integer and r is a :class:`timedelta` | 274 | | object. | 275 +--------------------------------+-----------------------------------------------+ 276 | ``+t1`` | Returns a :class:`timedelta` object with the | 277 | | same value. (2) | 278 +--------------------------------+-----------------------------------------------+ 279 | ``-t1`` | equivalent to | 280 | | :class:`timedelta`\ (-*t1.days*, | 281 | | -*t1.seconds*, -*t1.microseconds*), | 282 | | and to *t1*\* -1. (1)(4) | 283 +--------------------------------+-----------------------------------------------+ 284 | ``abs(t)`` | equivalent to +\ *t* when ``t.days >= 0``, and| 285 | | to -*t* when ``t.days < 0``. (2) | 286 +--------------------------------+-----------------------------------------------+ 287 | ``str(t)`` | Returns a string in the form | 288 | | ``[D day[s], ][H]H:MM:SS[.UUUUUU]``, where D | 289 | | is negative for negative ``t``. (5) | 290 +--------------------------------+-----------------------------------------------+ 291 | ``repr(t)`` | Returns a string representation of the | 292 | | :class:`timedelta` object as a constructor | 293 | | call with canonical attribute values. | 294 +--------------------------------+-----------------------------------------------+ 295 296 297 Notes: 298 299 (1) 300 This is exact, but may overflow. 301 302 (2) 303 This is exact, and cannot overflow. 304 305 (3) 306 Division by 0 raises :exc:`ZeroDivisionError`. 307 308 (4) 309 -*timedelta.max* is not representable as a :class:`timedelta` object. 310 311 (5) 312 String representations of :class:`timedelta` objects are normalized 313 similarly to their internal representation. This leads to somewhat 314 unusual results for negative timedeltas. For example: 315 316 >>> timedelta(hours=-5) 317 datetime.timedelta(days=-1, seconds=68400) 318 >>> print(_) 319 -1 day, 19:00:00 320 321 (6) 322 The expression ``t2 - t3`` will always be equal to the expression ``t2 + (-t3)`` except 323 when t3 is equal to ``timedelta.max``; in that case the former will produce a result 324 while the latter will overflow. 325 326 In addition to the operations listed above :class:`timedelta` objects support 327 certain additions and subtractions with :class:`date` and :class:`.datetime` 328 objects (see below). 329 330 .. versionchanged:: 3.2 331 Floor division and true division of a :class:`timedelta` object by another 332 :class:`timedelta` object are now supported, as are remainder operations and 333 the :func:`divmod` function. True division and multiplication of a 334 :class:`timedelta` object by a :class:`float` object are now supported. 335 336 337 Comparisons of :class:`timedelta` objects are supported with the 338 :class:`timedelta` object representing the smaller duration considered to be the 339 smaller timedelta. In order to stop mixed-type comparisons from falling back to 340 the default comparison by object address, when a :class:`timedelta` object is 341 compared to an object of a different type, :exc:`TypeError` is raised unless the 342 comparison is ``==`` or ``!=``. The latter cases return :const:`False` or 343 :const:`True`, respectively. 344 345 :class:`timedelta` objects are :term:`hashable` (usable as dictionary keys), support 346 efficient pickling, and in Boolean contexts, a :class:`timedelta` object is 347 considered to be true if and only if it isn't equal to ``timedelta(0)``. 348 349 Instance methods: 350 351 .. method:: timedelta.total_seconds() 352 353 Return the total number of seconds contained in the duration. Equivalent to 354 ``td / timedelta(seconds=1)``. 355 356 Note that for very large time intervals (greater than 270 years on 357 most platforms) this method will lose microsecond accuracy. 358 359 .. versionadded:: 3.2 360 361 362 Example usage: 363 364 >>> from datetime import timedelta 365 >>> year = timedelta(days=365) 366 >>> another_year = timedelta(weeks=40, days=84, hours=23, 367 ... minutes=50, seconds=600) # adds up to 365 days 368 >>> year.total_seconds() 369 31536000.0 370 >>> year == another_year 371 True 372 >>> ten_years = 10 * year 373 >>> ten_years, ten_years.days // 365 374 (datetime.timedelta(days=3650), 10) 375 >>> nine_years = ten_years - year 376 >>> nine_years, nine_years.days // 365 377 (datetime.timedelta(days=3285), 9) 378 >>> three_years = nine_years // 3 379 >>> three_years, three_years.days // 365 380 (datetime.timedelta(days=1095), 3) 381 >>> abs(three_years - ten_years) == 2 * three_years + year 382 True 383 384 385 .. _datetime-date: 386 387 :class:`date` Objects 388 --------------------- 389 390 A :class:`date` object represents a date (year, month and day) in an idealized 391 calendar, the current Gregorian calendar indefinitely extended in both 392 directions. January 1 of year 1 is called day number 1, January 2 of year 1 is 393 called day number 2, and so on. This matches the definition of the "proleptic 394 Gregorian" calendar in Dershowitz and Reingold's book Calendrical Calculations, 395 where it's the base calendar for all computations. See the book for algorithms 396 for converting between proleptic Gregorian ordinals and many other calendar 397 systems. 398 399 400 .. class:: date(year, month, day) 401 402 All arguments are required. Arguments may be integers, in the following 403 ranges: 404 405 * ``MINYEAR <= year <= MAXYEAR`` 406 * ``1 <= month <= 12`` 407 * ``1 <= day <= number of days in the given month and year`` 408 409 If an argument outside those ranges is given, :exc:`ValueError` is raised. 410 411 412 Other constructors, all class methods: 413 414 .. classmethod:: date.today() 415 416 Return the current local date. This is equivalent to 417 ``date.fromtimestamp(time.time())``. 418 419 420 .. classmethod:: date.fromtimestamp(timestamp) 421 422 Return the local date corresponding to the POSIX timestamp, such as is returned 423 by :func:`time.time`. This may raise :exc:`OverflowError`, if the timestamp is out 424 of the range of values supported by the platform C :c:func:`localtime` function, 425 and :exc:`OSError` on :c:func:`localtime` failure. 426 It's common for this to be restricted to years from 1970 through 2038. Note 427 that on non-POSIX systems that include leap seconds in their notion of a 428 timestamp, leap seconds are ignored by :meth:`fromtimestamp`. 429 430 .. versionchanged:: 3.3 431 Raise :exc:`OverflowError` instead of :exc:`ValueError` if the timestamp 432 is out of the range of values supported by the platform C 433 :c:func:`localtime` function. Raise :exc:`OSError` instead of 434 :exc:`ValueError` on :c:func:`localtime` failure. 435 436 437 .. classmethod:: date.fromordinal(ordinal) 438 439 Return the date corresponding to the proleptic Gregorian ordinal, where January 440 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1 <= ordinal <= 441 date.max.toordinal()``. For any date *d*, ``date.fromordinal(d.toordinal()) == 442 d``. 443 444 445 .. classmethod:: date.fromisoformat(date_string) 446 447 Return a :class:`date` corresponding to a *date_string* in the format emitted 448 by :meth:`date.isoformat`. Specifically, this function supports strings in 449 the format(s) ``YYYY-MM-DD``. 450 451 .. caution:: 452 453 This does not support parsing arbitrary ISO 8601 strings - it is only intended 454 as the inverse operation of :meth:`date.isoformat`. 455 456 .. versionadded:: 3.7 457 458 459 460 Class attributes: 461 462 .. attribute:: date.min 463 464 The earliest representable date, ``date(MINYEAR, 1, 1)``. 465 466 467 .. attribute:: date.max 468 469 The latest representable date, ``date(MAXYEAR, 12, 31)``. 470 471 472 .. attribute:: date.resolution 473 474 The smallest possible difference between non-equal date objects, 475 ``timedelta(days=1)``. 476 477 478 Instance attributes (read-only): 479 480 .. attribute:: date.year 481 482 Between :const:`MINYEAR` and :const:`MAXYEAR` inclusive. 483 484 485 .. attribute:: date.month 486 487 Between 1 and 12 inclusive. 488 489 490 .. attribute:: date.day 491 492 Between 1 and the number of days in the given month of the given year. 493 494 495 Supported operations: 496 497 +-------------------------------+----------------------------------------------+ 498 | Operation | Result | 499 +===============================+==============================================+ 500 | ``date2 = date1 + timedelta`` | *date2* is ``timedelta.days`` days removed | 501 | | from *date1*. (1) | 502 +-------------------------------+----------------------------------------------+ 503 | ``date2 = date1 - timedelta`` | Computes *date2* such that ``date2 + | 504 | | timedelta == date1``. (2) | 505 +-------------------------------+----------------------------------------------+ 506 | ``timedelta = date1 - date2`` | \(3) | 507 +-------------------------------+----------------------------------------------+ 508 | ``date1 < date2`` | *date1* is considered less than *date2* when | 509 | | *date1* precedes *date2* in time. (4) | 510 +-------------------------------+----------------------------------------------+ 511 512 Notes: 513 514 (1) 515 *date2* is moved forward in time if ``timedelta.days > 0``, or backward if 516 ``timedelta.days < 0``. Afterward ``date2 - date1 == timedelta.days``. 517 ``timedelta.seconds`` and ``timedelta.microseconds`` are ignored. 518 :exc:`OverflowError` is raised if ``date2.year`` would be smaller than 519 :const:`MINYEAR` or larger than :const:`MAXYEAR`. 520 521 (2) 522 ``timedelta.seconds`` and ``timedelta.microseconds`` are ignored. 523 524 (3) 525 This is exact, and cannot overflow. timedelta.seconds and 526 timedelta.microseconds are 0, and date2 + timedelta == date1 after. 527 528 (4) 529 In other words, ``date1 < date2`` if and only if ``date1.toordinal() < 530 date2.toordinal()``. Date comparison raises :exc:`TypeError` if 531 the other comparand isn't also a :class:`date` object. However, 532 ``NotImplemented`` is returned instead if the other comparand has a 533 :meth:`timetuple` attribute. This hook gives other kinds of date objects a 534 chance at implementing mixed-type comparison. If not, when a :class:`date` 535 object is compared to an object of a different type, :exc:`TypeError` is raised 536 unless the comparison is ``==`` or ``!=``. The latter cases return 537 :const:`False` or :const:`True`, respectively. 538 539 Dates can be used as dictionary keys. In Boolean contexts, all :class:`date` 540 objects are considered to be true. 541 542 Instance methods: 543 544 .. method:: date.replace(year=self.year, month=self.month, day=self.day) 545 546 Return a date with the same value, except for those parameters given new 547 values by whichever keyword arguments are specified. For example, if ``d == 548 date(2002, 12, 31)``, then ``d.replace(day=26) == date(2002, 12, 26)``. 549 550 551 .. method:: date.timetuple() 552 553 Return a :class:`time.struct_time` such as returned by :func:`time.localtime`. 554 The hours, minutes and seconds are 0, and the DST flag is -1. ``d.timetuple()`` 555 is equivalent to ``time.struct_time((d.year, d.month, d.day, 0, 0, 0, 556 d.weekday(), yday, -1))``, where ``yday = d.toordinal() - date(d.year, 1, 557 1).toordinal() + 1`` is the day number within the current year starting with 558 ``1`` for January 1st. 559 560 561 .. method:: date.toordinal() 562 563 Return the proleptic Gregorian ordinal of the date, where January 1 of year 1 564 has ordinal 1. For any :class:`date` object *d*, 565 ``date.fromordinal(d.toordinal()) == d``. 566 567 568 .. method:: date.weekday() 569 570 Return the day of the week as an integer, where Monday is 0 and Sunday is 6. 571 For example, ``date(2002, 12, 4).weekday() == 2``, a Wednesday. See also 572 :meth:`isoweekday`. 573 574 575 .. method:: date.isoweekday() 576 577 Return the day of the week as an integer, where Monday is 1 and Sunday is 7. 578 For example, ``date(2002, 12, 4).isoweekday() == 3``, a Wednesday. See also 579 :meth:`weekday`, :meth:`isocalendar`. 580 581 582 .. method:: date.isocalendar() 583 584 Return a 3-tuple, (ISO year, ISO week number, ISO weekday). 585 586 The ISO calendar is a widely used variant of the Gregorian calendar. See 587 https://www.staff.science.uu.nl/~gent0113/calendar/isocalendar.htm for a good 588 explanation. 589 590 The ISO year consists of 52 or 53 full weeks, and where a week starts on a 591 Monday and ends on a Sunday. The first week of an ISO year is the first 592 (Gregorian) calendar week of a year containing a Thursday. This is called week 593 number 1, and the ISO year of that Thursday is the same as its Gregorian year. 594 595 For example, 2004 begins on a Thursday, so the first week of ISO year 2004 596 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan 2004, so that 597 ``date(2003, 12, 29).isocalendar() == (2004, 1, 1)`` and ``date(2004, 1, 598 4).isocalendar() == (2004, 1, 7)``. 599 600 601 .. method:: date.isoformat() 602 603 Return a string representing the date in ISO 8601 format, 'YYYY-MM-DD'. For 604 example, ``date(2002, 12, 4).isoformat() == '2002-12-04'``. 605 606 607 .. method:: date.__str__() 608 609 For a date *d*, ``str(d)`` is equivalent to ``d.isoformat()``. 610 611 612 .. method:: date.ctime() 613 614 Return a string representing the date, for example ``date(2002, 12, 615 4).ctime() == 'Wed Dec 4 00:00:00 2002'``. ``d.ctime()`` is equivalent to 616 ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the native C 617 :c:func:`ctime` function (which :func:`time.ctime` invokes, but which 618 :meth:`date.ctime` does not invoke) conforms to the C standard. 619 620 621 .. method:: date.strftime(format) 622 623 Return a string representing the date, controlled by an explicit format string. 624 Format codes referring to hours, minutes or seconds will see 0 values. For a 625 complete list of formatting directives, see 626 :ref:`strftime-strptime-behavior`. 627 628 629 .. method:: date.__format__(format) 630 631 Same as :meth:`.date.strftime`. This makes it possible to specify a format 632 string for a :class:`.date` object in :ref:`formatted string 633 literals <f-strings>` and when using :meth:`str.format`. For a 634 complete list of formatting directives, see 635 :ref:`strftime-strptime-behavior`. 636 637 638 Example of counting days to an event:: 639 640 >>> import time 641 >>> from datetime import date 642 >>> today = date.today() 643 >>> today 644 datetime.date(2007, 12, 5) 645 >>> today == date.fromtimestamp(time.time()) 646 True 647 >>> my_birthday = date(today.year, 6, 24) 648 >>> if my_birthday < today: 649 ... my_birthday = my_birthday.replace(year=today.year + 1) 650 >>> my_birthday 651 datetime.date(2008, 6, 24) 652 >>> time_to_birthday = abs(my_birthday - today) 653 >>> time_to_birthday.days 654 202 655 656 Example of working with :class:`date`: 657 658 .. doctest:: 659 660 >>> from datetime import date 661 >>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001 662 >>> d 663 datetime.date(2002, 3, 11) 664 >>> t = d.timetuple() 665 >>> for i in t: # doctest: +SKIP 666 ... print(i) 667 2002 # year 668 3 # month 669 11 # day 670 0 671 0 672 0 673 0 # weekday (0 = Monday) 674 70 # 70th day in the year 675 -1 676 >>> ic = d.isocalendar() 677 >>> for i in ic: # doctest: +SKIP 678 ... print(i) 679 2002 # ISO year 680 11 # ISO week number 681 1 # ISO day number ( 1 = Monday ) 682 >>> d.isoformat() 683 '2002-03-11' 684 >>> d.strftime("%d/%m/%y") 685 '11/03/02' 686 >>> d.strftime("%A %d. %B %Y") 687 'Monday 11. March 2002' 688 >>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month") 689 'The day is 11, the month is March.' 690 691 692 .. _datetime-datetime: 693 694 :class:`.datetime` Objects 695 -------------------------- 696 697 A :class:`.datetime` object is a single object containing all the information 698 from a :class:`date` object and a :class:`.time` object. Like a :class:`date` 699 object, :class:`.datetime` assumes the current Gregorian calendar extended in 700 both directions; like a time object, :class:`.datetime` assumes there are exactly 701 3600\*24 seconds in every day. 702 703 Constructor: 704 705 .. class:: datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0) 706 707 The year, month and day arguments are required. *tzinfo* may be ``None``, or an 708 instance of a :class:`tzinfo` subclass. The remaining arguments may be integers, 709 in the following ranges: 710 711 * ``MINYEAR <= year <= MAXYEAR``, 712 * ``1 <= month <= 12``, 713 * ``1 <= day <= number of days in the given month and year``, 714 * ``0 <= hour < 24``, 715 * ``0 <= minute < 60``, 716 * ``0 <= second < 60``, 717 * ``0 <= microsecond < 1000000``, 718 * ``fold in [0, 1]``. 719 720 If an argument outside those ranges is given, :exc:`ValueError` is raised. 721 722 .. versionadded:: 3.6 723 Added the ``fold`` argument. 724 725 Other constructors, all class methods: 726 727 .. classmethod:: datetime.today() 728 729 Return the current local datetime, with :attr:`.tzinfo` ``None``. This is 730 equivalent to ``datetime.fromtimestamp(time.time())``. See also :meth:`now`, 731 :meth:`fromtimestamp`. 732 733 734 .. classmethod:: datetime.now(tz=None) 735 736 Return the current local date and time. If optional argument *tz* is ``None`` 737 or not specified, this is like :meth:`today`, but, if possible, supplies more 738 precision than can be gotten from going through a :func:`time.time` timestamp 739 (for example, this may be possible on platforms supplying the C 740 :c:func:`gettimeofday` function). 741 742 If *tz* is not ``None``, it must be an instance of a :class:`tzinfo` subclass, and the 743 current date and time are converted to *tz*s time zone. In this case the 744 result is equivalent to ``tz.fromutc(datetime.utcnow().replace(tzinfo=tz))``. 745 See also :meth:`today`, :meth:`utcnow`. 746 747 748 .. classmethod:: datetime.utcnow() 749 750 Return the current UTC date and time, with :attr:`.tzinfo` ``None``. This is like 751 :meth:`now`, but returns the current UTC date and time, as a naive 752 :class:`.datetime` object. An aware current UTC datetime can be obtained by 753 calling ``datetime.now(timezone.utc)``. See also :meth:`now`. 754 755 .. classmethod:: datetime.fromtimestamp(timestamp, tz=None) 756 757 Return the local date and time corresponding to the POSIX timestamp, such as is 758 returned by :func:`time.time`. If optional argument *tz* is ``None`` or not 759 specified, the timestamp is converted to the platform's local date and time, and 760 the returned :class:`.datetime` object is naive. 761 762 If *tz* is not ``None``, it must be an instance of a :class:`tzinfo` subclass, and the 763 timestamp is converted to *tz*s time zone. In this case the result is 764 equivalent to 765 ``tz.fromutc(datetime.utcfromtimestamp(timestamp).replace(tzinfo=tz))``. 766 767 :meth:`fromtimestamp` may raise :exc:`OverflowError`, if the timestamp is out of 768 the range of values supported by the platform C :c:func:`localtime` or 769 :c:func:`gmtime` functions, and :exc:`OSError` on :c:func:`localtime` or 770 :c:func:`gmtime` failure. 771 It's common for this to be restricted to years in 772 1970 through 2038. Note that on non-POSIX systems that include leap seconds in 773 their notion of a timestamp, leap seconds are ignored by :meth:`fromtimestamp`, 774 and then it's possible to have two timestamps differing by a second that yield 775 identical :class:`.datetime` objects. See also :meth:`utcfromtimestamp`. 776 777 .. versionchanged:: 3.3 778 Raise :exc:`OverflowError` instead of :exc:`ValueError` if the timestamp 779 is out of the range of values supported by the platform C 780 :c:func:`localtime` or :c:func:`gmtime` functions. Raise :exc:`OSError` 781 instead of :exc:`ValueError` on :c:func:`localtime` or :c:func:`gmtime` 782 failure. 783 784 .. versionchanged:: 3.6 785 :meth:`fromtimestamp` may return instances with :attr:`.fold` set to 1. 786 787 .. classmethod:: datetime.utcfromtimestamp(timestamp) 788 789 Return the UTC :class:`.datetime` corresponding to the POSIX timestamp, with 790 :attr:`.tzinfo` ``None``. This may raise :exc:`OverflowError`, if the timestamp is 791 out of the range of values supported by the platform C :c:func:`gmtime` function, 792 and :exc:`OSError` on :c:func:`gmtime` failure. 793 It's common for this to be restricted to years in 1970 through 2038. 794 795 To get an aware :class:`.datetime` object, call :meth:`fromtimestamp`:: 796 797 datetime.fromtimestamp(timestamp, timezone.utc) 798 799 On the POSIX compliant platforms, it is equivalent to the following 800 expression:: 801 802 datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp) 803 804 except the latter formula always supports the full years range: between 805 :const:`MINYEAR` and :const:`MAXYEAR` inclusive. 806 807 .. versionchanged:: 3.3 808 Raise :exc:`OverflowError` instead of :exc:`ValueError` if the timestamp 809 is out of the range of values supported by the platform C 810 :c:func:`gmtime` function. Raise :exc:`OSError` instead of 811 :exc:`ValueError` on :c:func:`gmtime` failure. 812 813 814 .. classmethod:: datetime.fromordinal(ordinal) 815 816 Return the :class:`.datetime` corresponding to the proleptic Gregorian ordinal, 817 where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1 818 <= ordinal <= datetime.max.toordinal()``. The hour, minute, second and 819 microsecond of the result are all 0, and :attr:`.tzinfo` is ``None``. 820 821 822 .. classmethod:: datetime.combine(date, time, tzinfo=self.tzinfo) 823 824 Return a new :class:`.datetime` object whose date components are equal to the 825 given :class:`date` object's, and whose time components 826 are equal to the given :class:`.time` object's. If the *tzinfo* 827 argument is provided, its value is used to set the :attr:`.tzinfo` attribute 828 of the result, otherwise the :attr:`~.time.tzinfo` attribute of the *time* argument 829 is used. 830 831 For any :class:`.datetime` object *d*, 832 ``d == datetime.combine(d.date(), d.time(), d.tzinfo)``. If date is a 833 :class:`.datetime` object, its time components and :attr:`.tzinfo` attributes 834 are ignored. 835 836 .. versionchanged:: 3.6 837 Added the *tzinfo* argument. 838 839 840 .. classmethod:: datetime.fromisoformat(date_string) 841 842 Return a :class:`datetime` corresponding to a *date_string* in one of the 843 formats emitted by :meth:`date.isoformat` and :meth:`datetime.isoformat`. 844 Specifically, this function supports strings in the format(s) 845 ``YYYY-MM-DD[*HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]]``, 846 where ``*`` can match any single character. 847 848 .. caution:: 849 850 This does not support parsing arbitrary ISO 8601 strings - it is only intended 851 as the inverse operation of :meth:`datetime.isoformat`. 852 853 .. versionadded:: 3.7 854 855 .. classmethod:: datetime.strptime(date_string, format) 856 857 Return a :class:`.datetime` corresponding to *date_string*, parsed according to 858 *format*. This is equivalent to ``datetime(*(time.strptime(date_string, 859 format)[0:6]))``. :exc:`ValueError` is raised if the date_string and format 860 can't be parsed by :func:`time.strptime` or if it returns a value which isn't a 861 time tuple. For a complete list of formatting directives, see 862 :ref:`strftime-strptime-behavior`. 863 864 865 866 Class attributes: 867 868 .. attribute:: datetime.min 869 870 The earliest representable :class:`.datetime`, ``datetime(MINYEAR, 1, 1, 871 tzinfo=None)``. 872 873 874 .. attribute:: datetime.max 875 876 The latest representable :class:`.datetime`, ``datetime(MAXYEAR, 12, 31, 23, 59, 877 59, 999999, tzinfo=None)``. 878 879 880 .. attribute:: datetime.resolution 881 882 The smallest possible difference between non-equal :class:`.datetime` objects, 883 ``timedelta(microseconds=1)``. 884 885 886 Instance attributes (read-only): 887 888 .. attribute:: datetime.year 889 890 Between :const:`MINYEAR` and :const:`MAXYEAR` inclusive. 891 892 893 .. attribute:: datetime.month 894 895 Between 1 and 12 inclusive. 896 897 898 .. attribute:: datetime.day 899 900 Between 1 and the number of days in the given month of the given year. 901 902 903 .. attribute:: datetime.hour 904 905 In ``range(24)``. 906 907 908 .. attribute:: datetime.minute 909 910 In ``range(60)``. 911 912 913 .. attribute:: datetime.second 914 915 In ``range(60)``. 916 917 918 .. attribute:: datetime.microsecond 919 920 In ``range(1000000)``. 921 922 923 .. attribute:: datetime.tzinfo 924 925 The object passed as the *tzinfo* argument to the :class:`.datetime` constructor, 926 or ``None`` if none was passed. 927 928 929 .. attribute:: datetime.fold 930 931 In ``[0, 1]``. Used to disambiguate wall times during a repeated interval. (A 932 repeated interval occurs when clocks are rolled back at the end of daylight saving 933 time or when the UTC offset for the current zone is decreased for political reasons.) 934 The value 0 (1) represents the earlier (later) of the two moments with the same wall 935 time representation. 936 937 .. versionadded:: 3.6 938 939 Supported operations: 940 941 +---------------------------------------+--------------------------------+ 942 | Operation | Result | 943 +=======================================+================================+ 944 | ``datetime2 = datetime1 + timedelta`` | \(1) | 945 +---------------------------------------+--------------------------------+ 946 | ``datetime2 = datetime1 - timedelta`` | \(2) | 947 +---------------------------------------+--------------------------------+ 948 | ``timedelta = datetime1 - datetime2`` | \(3) | 949 +---------------------------------------+--------------------------------+ 950 | ``datetime1 < datetime2`` | Compares :class:`.datetime` to | 951 | | :class:`.datetime`. (4) | 952 +---------------------------------------+--------------------------------+ 953 954 (1) 955 datetime2 is a duration of timedelta removed from datetime1, moving forward in 956 time if ``timedelta.days`` > 0, or backward if ``timedelta.days`` < 0. The 957 result has the same :attr:`~.datetime.tzinfo` attribute as the input datetime, and 958 datetime2 - datetime1 == timedelta after. :exc:`OverflowError` is raised if 959 datetime2.year would be smaller than :const:`MINYEAR` or larger than 960 :const:`MAXYEAR`. Note that no time zone adjustments are done even if the 961 input is an aware object. 962 963 (2) 964 Computes the datetime2 such that datetime2 + timedelta == datetime1. As for 965 addition, the result has the same :attr:`~.datetime.tzinfo` attribute as the input 966 datetime, and no time zone adjustments are done even if the input is aware. 967 968 (3) 969 Subtraction of a :class:`.datetime` from a :class:`.datetime` is defined only if 970 both operands are naive, or if both are aware. If one is aware and the other is 971 naive, :exc:`TypeError` is raised. 972 973 If both are naive, or both are aware and have the same :attr:`~.datetime.tzinfo` attribute, 974 the :attr:`~.datetime.tzinfo` attributes are ignored, and the result is a :class:`timedelta` 975 object *t* such that ``datetime2 + t == datetime1``. No time zone adjustments 976 are done in this case. 977 978 If both are aware and have different :attr:`~.datetime.tzinfo` attributes, ``a-b`` acts 979 as if *a* and *b* were first converted to naive UTC datetimes first. The 980 result is ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) 981 - b.utcoffset())`` except that the implementation never overflows. 982 983 (4) 984 *datetime1* is considered less than *datetime2* when *datetime1* precedes 985 *datetime2* in time. 986 987 If one comparand is naive and the other is aware, :exc:`TypeError` 988 is raised if an order comparison is attempted. For equality 989 comparisons, naive instances are never equal to aware instances. 990 991 If both comparands are aware, and have the same :attr:`~.datetime.tzinfo` attribute, the 992 common :attr:`~.datetime.tzinfo` attribute is ignored and the base datetimes are 993 compared. If both comparands are aware and have different :attr:`~.datetime.tzinfo` 994 attributes, the comparands are first adjusted by subtracting their UTC 995 offsets (obtained from ``self.utcoffset()``). 996 997 .. versionchanged:: 3.3 998 Equality comparisons between naive and aware :class:`.datetime` 999 instances don't raise :exc:`TypeError`. 1000 1001 .. note:: 1002 1003 In order to stop comparison from falling back to the default scheme of comparing 1004 object addresses, datetime comparison normally raises :exc:`TypeError` if the 1005 other comparand isn't also a :class:`.datetime` object. However, 1006 ``NotImplemented`` is returned instead if the other comparand has a 1007 :meth:`timetuple` attribute. This hook gives other kinds of date objects a 1008 chance at implementing mixed-type comparison. If not, when a :class:`.datetime` 1009 object is compared to an object of a different type, :exc:`TypeError` is raised 1010 unless the comparison is ``==`` or ``!=``. The latter cases return 1011 :const:`False` or :const:`True`, respectively. 1012 1013 :class:`.datetime` objects can be used as dictionary keys. In Boolean contexts, 1014 all :class:`.datetime` objects are considered to be true. 1015 1016 Instance methods: 1017 1018 .. method:: datetime.date() 1019 1020 Return :class:`date` object with same year, month and day. 1021 1022 1023 .. method:: datetime.time() 1024 1025 Return :class:`.time` object with same hour, minute, second, microsecond and fold. 1026 :attr:`.tzinfo` is ``None``. See also method :meth:`timetz`. 1027 1028 .. versionchanged:: 3.6 1029 The fold value is copied to the returned :class:`.time` object. 1030 1031 1032 .. method:: datetime.timetz() 1033 1034 Return :class:`.time` object with same hour, minute, second, microsecond, fold, and 1035 tzinfo attributes. See also method :meth:`time`. 1036 1037 .. versionchanged:: 3.6 1038 The fold value is copied to the returned :class:`.time` object. 1039 1040 1041 .. method:: datetime.replace(year=self.year, month=self.month, day=self.day, \ 1042 hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, \ 1043 tzinfo=self.tzinfo, * fold=0) 1044 1045 Return a datetime with the same attributes, except for those attributes given 1046 new values by whichever keyword arguments are specified. Note that 1047 ``tzinfo=None`` can be specified to create a naive datetime from an aware 1048 datetime with no conversion of date and time data. 1049 1050 .. versionadded:: 3.6 1051 Added the ``fold`` argument. 1052 1053 1054 .. method:: datetime.astimezone(tz=None) 1055 1056 Return a :class:`.datetime` object with new :attr:`.tzinfo` attribute *tz*, 1057 adjusting the date and time data so the result is the same UTC time as 1058 *self*, but in *tz*'s local time. 1059 1060 If provided, *tz* must be an instance of a :class:`tzinfo` subclass, and its 1061 :meth:`utcoffset` and :meth:`dst` methods must not return ``None``. If *self* 1062 is naive, it is presumed to represent time in the system timezone. 1063 1064 If called without arguments (or with ``tz=None``) the system local 1065 timezone is assumed for the target timezone. The ``.tzinfo`` attribute of the converted 1066 datetime instance will be set to an instance of :class:`timezone` 1067 with the zone name and offset obtained from the OS. 1068 1069 If ``self.tzinfo`` is *tz*, ``self.astimezone(tz)`` is equal to *self*: no 1070 adjustment of date or time data is performed. Else the result is local 1071 time in the timezone *tz*, representing the same UTC time as *self*: after 1072 ``astz = dt.astimezone(tz)``, ``astz - astz.utcoffset()`` will have 1073 the same date and time data as ``dt - dt.utcoffset()``. 1074 1075 If you merely want to attach a time zone object *tz* to a datetime *dt* without 1076 adjustment of date and time data, use ``dt.replace(tzinfo=tz)``. If you 1077 merely want to remove the time zone object from an aware datetime *dt* without 1078 conversion of date and time data, use ``dt.replace(tzinfo=None)``. 1079 1080 Note that the default :meth:`tzinfo.fromutc` method can be overridden in a 1081 :class:`tzinfo` subclass to affect the result returned by :meth:`astimezone`. 1082 Ignoring error cases, :meth:`astimezone` acts like:: 1083 1084 def astimezone(self, tz): 1085 if self.tzinfo is tz: 1086 return self 1087 # Convert self to UTC, and attach the new time zone object. 1088 utc = (self - self.utcoffset()).replace(tzinfo=tz) 1089 # Convert from UTC to tz's local time. 1090 return tz.fromutc(utc) 1091 1092 .. versionchanged:: 3.3 1093 *tz* now can be omitted. 1094 1095 .. versionchanged:: 3.6 1096 The :meth:`astimezone` method can now be called on naive instances that 1097 are presumed to represent system local time. 1098 1099 1100 .. method:: datetime.utcoffset() 1101 1102 If :attr:`.tzinfo` is ``None``, returns ``None``, else returns 1103 ``self.tzinfo.utcoffset(self)``, and raises an exception if the latter doesn't 1104 return ``None`` or a :class:`timedelta` object with magnitude less than one day. 1105 1106 .. versionchanged:: 3.7 1107 The UTC offset is not restricted to a whole number of minutes. 1108 1109 1110 .. method:: datetime.dst() 1111 1112 If :attr:`.tzinfo` is ``None``, returns ``None``, else returns 1113 ``self.tzinfo.dst(self)``, and raises an exception if the latter doesn't return 1114 ``None`` or a :class:`timedelta` object with magnitude less than one day. 1115 1116 .. versionchanged:: 3.7 1117 The DST offset is not restricted to a whole number of minutes. 1118 1119 1120 .. method:: datetime.tzname() 1121 1122 If :attr:`.tzinfo` is ``None``, returns ``None``, else returns 1123 ``self.tzinfo.tzname(self)``, raises an exception if the latter doesn't return 1124 ``None`` or a string object, 1125 1126 1127 .. method:: datetime.timetuple() 1128 1129 Return a :class:`time.struct_time` such as returned by :func:`time.localtime`. 1130 ``d.timetuple()`` is equivalent to ``time.struct_time((d.year, d.month, d.day, 1131 d.hour, d.minute, d.second, d.weekday(), yday, dst))``, where ``yday = 1132 d.toordinal() - date(d.year, 1, 1).toordinal() + 1`` is the day number within 1133 the current year starting with ``1`` for January 1st. The :attr:`tm_isdst` flag 1134 of the result is set according to the :meth:`dst` method: :attr:`.tzinfo` is 1135 ``None`` or :meth:`dst` returns ``None``, :attr:`tm_isdst` is set to ``-1``; 1136 else if :meth:`dst` returns a non-zero value, :attr:`tm_isdst` is set to ``1``; 1137 else :attr:`tm_isdst` is set to ``0``. 1138 1139 1140 .. method:: datetime.utctimetuple() 1141 1142 If :class:`.datetime` instance *d* is naive, this is the same as 1143 ``d.timetuple()`` except that :attr:`tm_isdst` is forced to 0 regardless of what 1144 ``d.dst()`` returns. DST is never in effect for a UTC time. 1145 1146 If *d* is aware, *d* is normalized to UTC time, by subtracting 1147 ``d.utcoffset()``, and a :class:`time.struct_time` for the 1148 normalized time is returned. :attr:`tm_isdst` is forced to 0. Note 1149 that an :exc:`OverflowError` may be raised if *d*.year was 1150 ``MINYEAR`` or ``MAXYEAR`` and UTC adjustment spills over a year 1151 boundary. 1152 1153 1154 .. method:: datetime.toordinal() 1155 1156 Return the proleptic Gregorian ordinal of the date. The same as 1157 ``self.date().toordinal()``. 1158 1159 .. method:: datetime.timestamp() 1160 1161 Return POSIX timestamp corresponding to the :class:`.datetime` 1162 instance. The return value is a :class:`float` similar to that 1163 returned by :func:`time.time`. 1164 1165 Naive :class:`.datetime` instances are assumed to represent local 1166 time and this method relies on the platform C :c:func:`mktime` 1167 function to perform the conversion. Since :class:`.datetime` 1168 supports wider range of values than :c:func:`mktime` on many 1169 platforms, this method may raise :exc:`OverflowError` for times far 1170 in the past or far in the future. 1171 1172 For aware :class:`.datetime` instances, the return value is computed 1173 as:: 1174 1175 (dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds() 1176 1177 .. versionadded:: 3.3 1178 1179 .. versionchanged:: 3.6 1180 The :meth:`timestamp` method uses the :attr:`.fold` attribute to 1181 disambiguate the times during a repeated interval. 1182 1183 .. note:: 1184 1185 There is no method to obtain the POSIX timestamp directly from a 1186 naive :class:`.datetime` instance representing UTC time. If your 1187 application uses this convention and your system timezone is not 1188 set to UTC, you can obtain the POSIX timestamp by supplying 1189 ``tzinfo=timezone.utc``:: 1190 1191 timestamp = dt.replace(tzinfo=timezone.utc).timestamp() 1192 1193 or by calculating the timestamp directly:: 1194 1195 timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1) 1196 1197 .. method:: datetime.weekday() 1198 1199 Return the day of the week as an integer, where Monday is 0 and Sunday is 6. 1200 The same as ``self.date().weekday()``. See also :meth:`isoweekday`. 1201 1202 1203 .. method:: datetime.isoweekday() 1204 1205 Return the day of the week as an integer, where Monday is 1 and Sunday is 7. 1206 The same as ``self.date().isoweekday()``. See also :meth:`weekday`, 1207 :meth:`isocalendar`. 1208 1209 1210 .. method:: datetime.isocalendar() 1211 1212 Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The same as 1213 ``self.date().isocalendar()``. 1214 1215 1216 .. method:: datetime.isoformat(sep='T', timespec='auto') 1217 1218 Return a string representing the date and time in ISO 8601 format, 1219 YYYY-MM-DDTHH:MM:SS.ffffff or, if :attr:`microsecond` is 0, 1220 YYYY-MM-DDTHH:MM:SS 1221 1222 If :meth:`utcoffset` does not return ``None``, a string is 1223 appended, giving the UTC offset: 1224 YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]] or, if :attr:`microsecond` 1225 is 0 YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]. 1226 1227 The optional argument *sep* (default ``'T'``) is a one-character separator, 1228 placed between the date and time portions of the result. For example, 1229 1230 >>> from datetime import tzinfo, timedelta, datetime 1231 >>> class TZ(tzinfo): 1232 ... def utcoffset(self, dt): return timedelta(minutes=-399) 1233 ... 1234 >>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ') 1235 '2002-12-25 00:00:00-06:39' 1236 1237 The optional argument *timespec* specifies the number of additional 1238 components of the time to include (the default is ``'auto'``). 1239 It can be one of the following: 1240 1241 - ``'auto'``: Same as ``'seconds'`` if :attr:`microsecond` is 0, 1242 same as ``'microseconds'`` otherwise. 1243 - ``'hours'``: Include the :attr:`hour` in the two-digit HH format. 1244 - ``'minutes'``: Include :attr:`hour` and :attr:`minute` in HH:MM format. 1245 - ``'seconds'``: Include :attr:`hour`, :attr:`minute`, and :attr:`second` 1246 in HH:MM:SS format. 1247 - ``'milliseconds'``: Include full time, but truncate fractional second 1248 part to milliseconds. HH:MM:SS.sss format. 1249 - ``'microseconds'``: Include full time in HH:MM:SS.ffffff format. 1250 1251 .. note:: 1252 1253 Excluded time components are truncated, not rounded. 1254 1255 :exc:`ValueError` will be raised on an invalid *timespec* argument. 1256 1257 1258 >>> from datetime import datetime 1259 >>> datetime.now().isoformat(timespec='minutes') # doctest: +SKIP 1260 '2002-12-25T00:00' 1261 >>> dt = datetime(2015, 1, 1, 12, 30, 59, 0) 1262 >>> dt.isoformat(timespec='microseconds') 1263 '2015-01-01T12:30:59.000000' 1264 1265 .. versionadded:: 3.6 1266 Added the *timespec* argument. 1267 1268 1269 .. method:: datetime.__str__() 1270 1271 For a :class:`.datetime` instance *d*, ``str(d)`` is equivalent to 1272 ``d.isoformat(' ')``. 1273 1274 1275 .. method:: datetime.ctime() 1276 1277 Return a string representing the date and time, for example ``datetime(2002, 12, 1278 4, 20, 30, 40).ctime() == 'Wed Dec 4 20:30:40 2002'``. ``d.ctime()`` is 1279 equivalent to ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the 1280 native C :c:func:`ctime` function (which :func:`time.ctime` invokes, but which 1281 :meth:`datetime.ctime` does not invoke) conforms to the C standard. 1282 1283 1284 .. method:: datetime.strftime(format) 1285 1286 Return a string representing the date and time, controlled by an explicit format 1287 string. For a complete list of formatting directives, see 1288 :ref:`strftime-strptime-behavior`. 1289 1290 1291 .. method:: datetime.__format__(format) 1292 1293 Same as :meth:`.datetime.strftime`. This makes it possible to specify a format 1294 string for a :class:`.datetime` object in :ref:`formatted string 1295 literals <f-strings>` and when using :meth:`str.format`. For a 1296 complete list of formatting directives, see 1297 :ref:`strftime-strptime-behavior`. 1298 1299 1300 Examples of working with datetime objects: 1301 1302 .. doctest:: 1303 1304 >>> from datetime import datetime, date, time 1305 >>> # Using datetime.combine() 1306 >>> d = date(2005, 7, 14) 1307 >>> t = time(12, 30) 1308 >>> datetime.combine(d, t) 1309 datetime.datetime(2005, 7, 14, 12, 30) 1310 >>> # Using datetime.now() or datetime.utcnow() 1311 >>> datetime.now() # doctest: +SKIP 1312 datetime.datetime(2007, 12, 6, 16, 29, 43, 79043) # GMT +1 1313 >>> datetime.utcnow() # doctest: +SKIP 1314 datetime.datetime(2007, 12, 6, 15, 29, 43, 79060) 1315 >>> # Using datetime.strptime() 1316 >>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M") 1317 >>> dt 1318 datetime.datetime(2006, 11, 21, 16, 30) 1319 >>> # Using datetime.timetuple() to get tuple of all attributes 1320 >>> tt = dt.timetuple() 1321 >>> for it in tt: # doctest: +SKIP 1322 ... print(it) 1323 ... 1324 2006 # year 1325 11 # month 1326 21 # day 1327 16 # hour 1328 30 # minute 1329 0 # second 1330 1 # weekday (0 = Monday) 1331 325 # number of days since 1st January 1332 -1 # dst - method tzinfo.dst() returned None 1333 >>> # Date in ISO format 1334 >>> ic = dt.isocalendar() 1335 >>> for it in ic: # doctest: +SKIP 1336 ... print(it) 1337 ... 1338 2006 # ISO year 1339 47 # ISO week 1340 2 # ISO weekday 1341 >>> # Formatting datetime 1342 >>> dt.strftime("%A, %d. %B %Y %I:%M%p") 1343 'Tuesday, 21. November 2006 04:30PM' 1344 >>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'.format(dt, "day", "month", "time") 1345 'The day is 21, the month is November, the time is 04:30PM.' 1346 1347 Using datetime with tzinfo: 1348 1349 >>> from datetime import timedelta, datetime, tzinfo 1350 >>> class GMT1(tzinfo): 1351 ... def utcoffset(self, dt): 1352 ... return timedelta(hours=1) + self.dst(dt) 1353 ... def dst(self, dt): 1354 ... # DST starts last Sunday in March 1355 ... d = datetime(dt.year, 4, 1) # ends last Sunday in October 1356 ... self.dston = d - timedelta(days=d.weekday() + 1) 1357 ... d = datetime(dt.year, 11, 1) 1358 ... self.dstoff = d - timedelta(days=d.weekday() + 1) 1359 ... if self.dston <= dt.replace(tzinfo=None) < self.dstoff: 1360 ... return timedelta(hours=1) 1361 ... else: 1362 ... return timedelta(0) 1363 ... def tzname(self,dt): 1364 ... return "GMT +1" 1365 ... 1366 >>> class GMT2(tzinfo): 1367 ... def utcoffset(self, dt): 1368 ... return timedelta(hours=2) + self.dst(dt) 1369 ... def dst(self, dt): 1370 ... d = datetime(dt.year, 4, 1) 1371 ... self.dston = d - timedelta(days=d.weekday() + 1) 1372 ... d = datetime(dt.year, 11, 1) 1373 ... self.dstoff = d - timedelta(days=d.weekday() + 1) 1374 ... if self.dston <= dt.replace(tzinfo=None) < self.dstoff: 1375 ... return timedelta(hours=1) 1376 ... else: 1377 ... return timedelta(0) 1378 ... def tzname(self,dt): 1379 ... return "GMT +2" 1380 ... 1381 >>> gmt1 = GMT1() 1382 >>> # Daylight Saving Time 1383 >>> dt1 = datetime(2006, 11, 21, 16, 30, tzinfo=gmt1) 1384 >>> dt1.dst() 1385 datetime.timedelta(0) 1386 >>> dt1.utcoffset() 1387 datetime.timedelta(seconds=3600) 1388 >>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=gmt1) 1389 >>> dt2.dst() 1390 datetime.timedelta(seconds=3600) 1391 >>> dt2.utcoffset() 1392 datetime.timedelta(seconds=7200) 1393 >>> # Convert datetime to another time zone 1394 >>> dt3 = dt2.astimezone(GMT2()) 1395 >>> dt3 # doctest: +ELLIPSIS 1396 datetime.datetime(2006, 6, 14, 14, 0, tzinfo=<GMT2 object at 0x...>) 1397 >>> dt2 # doctest: +ELLIPSIS 1398 datetime.datetime(2006, 6, 14, 13, 0, tzinfo=<GMT1 object at 0x...>) 1399 >>> dt2.utctimetuple() == dt3.utctimetuple() 1400 True 1401 1402 1403 1404 .. _datetime-time: 1405 1406 :class:`.time` Objects 1407 ---------------------- 1408 1409 A time object represents a (local) time of day, independent of any particular 1410 day, and subject to adjustment via a :class:`tzinfo` object. 1411 1412 .. class:: time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0) 1413 1414 All arguments are optional. *tzinfo* may be ``None``, or an instance of a 1415 :class:`tzinfo` subclass. The remaining arguments may be integers, in the 1416 following ranges: 1417 1418 * ``0 <= hour < 24``, 1419 * ``0 <= minute < 60``, 1420 * ``0 <= second < 60``, 1421 * ``0 <= microsecond < 1000000``, 1422 * ``fold in [0, 1]``. 1423 1424 If an argument outside those ranges is given, :exc:`ValueError` is raised. All 1425 default to ``0`` except *tzinfo*, which defaults to :const:`None`. 1426 1427 Class attributes: 1428 1429 1430 .. attribute:: time.min 1431 1432 The earliest representable :class:`.time`, ``time(0, 0, 0, 0)``. 1433 1434 1435 .. attribute:: time.max 1436 1437 The latest representable :class:`.time`, ``time(23, 59, 59, 999999)``. 1438 1439 1440 .. attribute:: time.resolution 1441 1442 The smallest possible difference between non-equal :class:`.time` objects, 1443 ``timedelta(microseconds=1)``, although note that arithmetic on 1444 :class:`.time` objects is not supported. 1445 1446 1447 Instance attributes (read-only): 1448 1449 .. attribute:: time.hour 1450 1451 In ``range(24)``. 1452 1453 1454 .. attribute:: time.minute 1455 1456 In ``range(60)``. 1457 1458 1459 .. attribute:: time.second 1460 1461 In ``range(60)``. 1462 1463 1464 .. attribute:: time.microsecond 1465 1466 In ``range(1000000)``. 1467 1468 1469 .. attribute:: time.tzinfo 1470 1471 The object passed as the tzinfo argument to the :class:`.time` constructor, or 1472 ``None`` if none was passed. 1473 1474 1475 .. attribute:: time.fold 1476 1477 In ``[0, 1]``. Used to disambiguate wall times during a repeated interval. (A 1478 repeated interval occurs when clocks are rolled back at the end of daylight saving 1479 time or when the UTC offset for the current zone is decreased for political reasons.) 1480 The value 0 (1) represents the earlier (later) of the two moments with the same wall 1481 time representation. 1482 1483 .. versionadded:: 3.6 1484 1485 1486 Supported operations: 1487 1488 * comparison of :class:`.time` to :class:`.time`, where *a* is considered less 1489 than *b* when *a* precedes *b* in time. If one comparand is naive and the other 1490 is aware, :exc:`TypeError` is raised if an order comparison is attempted. For equality 1491 comparisons, naive instances are never equal to aware instances. 1492 1493 If both comparands are aware, and have 1494 the same :attr:`~time.tzinfo` attribute, the common :attr:`~time.tzinfo` attribute is 1495 ignored and the base times are compared. If both comparands are aware and 1496 have different :attr:`~time.tzinfo` attributes, the comparands are first adjusted by 1497 subtracting their UTC offsets (obtained from ``self.utcoffset()``). In order 1498 to stop mixed-type comparisons from falling back to the default comparison by 1499 object address, when a :class:`.time` object is compared to an object of a 1500 different type, :exc:`TypeError` is raised unless the comparison is ``==`` or 1501 ``!=``. The latter cases return :const:`False` or :const:`True`, respectively. 1502 1503 .. versionchanged:: 3.3 1504 Equality comparisons between naive and aware :class:`~datetime.time` instances 1505 don't raise :exc:`TypeError`. 1506 1507 * hash, use as dict key 1508 1509 * efficient pickling 1510 1511 In boolean contexts, a :class:`.time` object is always considered to be true. 1512 1513 .. versionchanged:: 3.5 1514 Before Python 3.5, a :class:`.time` object was considered to be false if it 1515 represented midnight in UTC. This behavior was considered obscure and 1516 error-prone and has been removed in Python 3.5. See :issue:`13936` for full 1517 details. 1518 1519 1520 Other constructor: 1521 1522 .. classmethod:: time.fromisoformat(time_string) 1523 1524 Return a :class:`time` corresponding to a *time_string* in one of the 1525 formats emitted by :meth:`time.isoformat`. Specifically, this function supports 1526 strings in the format(s) ``HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]``. 1527 1528 .. caution:: 1529 1530 This does not support parsing arbitrary ISO 8601 strings - it is only intended 1531 as the inverse operation of :meth:`time.isoformat`. 1532 1533 .. versionadded:: 3.7 1534 1535 1536 Instance methods: 1537 1538 .. method:: time.replace(hour=self.hour, minute=self.minute, second=self.second, \ 1539 microsecond=self.microsecond, tzinfo=self.tzinfo, * fold=0) 1540 1541 Return a :class:`.time` with the same value, except for those attributes given 1542 new values by whichever keyword arguments are specified. Note that 1543 ``tzinfo=None`` can be specified to create a naive :class:`.time` from an 1544 aware :class:`.time`, without conversion of the time data. 1545 1546 .. versionadded:: 3.6 1547 Added the ``fold`` argument. 1548 1549 1550 .. method:: time.isoformat(timespec='auto') 1551 1552 Return a string representing the time in ISO 8601 format, HH:MM:SS.ffffff or, if 1553 :attr:`microsecond` is 0, HH:MM:SS If :meth:`utcoffset` does not return ``None``, a 1554 string is appended, giving the UTC offset: HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]] 1555 or, if self.microsecond is 0, HH:MM:SS+HH:MM[:SS[.ffffff]]. 1556 1557 The optional argument *timespec* specifies the number of additional 1558 components of the time to include (the default is ``'auto'``). 1559 It can be one of the following: 1560 1561 - ``'auto'``: Same as ``'seconds'`` if :attr:`microsecond` is 0, 1562 same as ``'microseconds'`` otherwise. 1563 - ``'hours'``: Include the :attr:`hour` in the two-digit HH format. 1564 - ``'minutes'``: Include :attr:`hour` and :attr:`minute` in HH:MM format. 1565 - ``'seconds'``: Include :attr:`hour`, :attr:`minute`, and :attr:`second` 1566 in HH:MM:SS format. 1567 - ``'milliseconds'``: Include full time, but truncate fractional second 1568 part to milliseconds. HH:MM:SS.sss format. 1569 - ``'microseconds'``: Include full time in HH:MM:SS.ffffff format. 1570 1571 .. note:: 1572 1573 Excluded time components are truncated, not rounded. 1574 1575 :exc:`ValueError` will be raised on an invalid *timespec* argument. 1576 1577 1578 >>> from datetime import time 1579 >>> time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes') 1580 '12:34' 1581 >>> dt = time(hour=12, minute=34, second=56, microsecond=0) 1582 >>> dt.isoformat(timespec='microseconds') 1583 '12:34:56.000000' 1584 >>> dt.isoformat(timespec='auto') 1585 '12:34:56' 1586 1587 .. versionadded:: 3.6 1588 Added the *timespec* argument. 1589 1590 1591 .. method:: time.__str__() 1592 1593 For a time *t*, ``str(t)`` is equivalent to ``t.isoformat()``. 1594 1595 1596 .. method:: time.strftime(format) 1597 1598 Return a string representing the time, controlled by an explicit format 1599 string. For a complete list of formatting directives, see 1600 :ref:`strftime-strptime-behavior`. 1601 1602 1603 .. method:: time.__format__(format) 1604 1605 Same as :meth:`.time.strftime`. This makes it possible to specify a format string 1606 for a :class:`.time` object in :ref:`formatted string 1607 literals <f-strings>` and when using :meth:`str.format`. For a 1608 complete list of formatting directives, see 1609 :ref:`strftime-strptime-behavior`. 1610 1611 1612 .. method:: time.utcoffset() 1613 1614 If :attr:`.tzinfo` is ``None``, returns ``None``, else returns 1615 ``self.tzinfo.utcoffset(None)``, and raises an exception if the latter doesn't 1616 return ``None`` or a :class:`timedelta` object with magnitude less than one day. 1617 1618 .. versionchanged:: 3.7 1619 The UTC offset is not restricted to a whole number of minutes. 1620 1621 1622 .. method:: time.dst() 1623 1624 If :attr:`.tzinfo` is ``None``, returns ``None``, else returns 1625 ``self.tzinfo.dst(None)``, and raises an exception if the latter doesn't return 1626 ``None``, or a :class:`timedelta` object with magnitude less than one day. 1627 1628 .. versionchanged:: 3.7 1629 The DST offset is not restricted to a whole number of minutes. 1630 1631 .. method:: time.tzname() 1632 1633 If :attr:`.tzinfo` is ``None``, returns ``None``, else returns 1634 ``self.tzinfo.tzname(None)``, or raises an exception if the latter doesn't 1635 return ``None`` or a string object. 1636 1637 Example: 1638 1639 >>> from datetime import time, tzinfo, timedelta 1640 >>> class GMT1(tzinfo): 1641 ... def utcoffset(self, dt): 1642 ... return timedelta(hours=1) 1643 ... def dst(self, dt): 1644 ... return timedelta(0) 1645 ... def tzname(self,dt): 1646 ... return "Europe/Prague" 1647 ... 1648 >>> t = time(12, 10, 30, tzinfo=GMT1()) 1649 >>> t # doctest: +ELLIPSIS 1650 datetime.time(12, 10, 30, tzinfo=<GMT1 object at 0x...>) 1651 >>> gmt = GMT1() 1652 >>> t.isoformat() 1653 '12:10:30+01:00' 1654 >>> t.dst() 1655 datetime.timedelta(0) 1656 >>> t.tzname() 1657 'Europe/Prague' 1658 >>> t.strftime("%H:%M:%S %Z") 1659 '12:10:30 Europe/Prague' 1660 >>> 'The {} is {:%H:%M}.'.format("time", t) 1661 'The time is 12:10.' 1662 1663 1664 .. _datetime-tzinfo: 1665 1666 :class:`tzinfo` Objects 1667 ----------------------- 1668 1669 .. class:: tzinfo() 1670 1671 This is an abstract base class, meaning that this class should not be 1672 instantiated directly. You need to derive a concrete subclass, and (at least) 1673 supply implementations of the standard :class:`tzinfo` methods needed by the 1674 :class:`.datetime` methods you use. The :mod:`datetime` module supplies 1675 a simple concrete subclass of :class:`tzinfo`, :class:`timezone`, which can represent 1676 timezones with fixed offset from UTC such as UTC itself or North American EST and 1677 EDT. 1678 1679 An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the 1680 constructors for :class:`.datetime` and :class:`.time` objects. The latter objects 1681 view their attributes as being in local time, and the :class:`tzinfo` object 1682 supports methods revealing offset of local time from UTC, the name of the time 1683 zone, and DST offset, all relative to a date or time object passed to them. 1684 1685 Special requirement for pickling: A :class:`tzinfo` subclass must have an 1686 :meth:`__init__` method that can be called with no arguments, else it can be 1687 pickled but possibly not unpickled again. This is a technical requirement that 1688 may be relaxed in the future. 1689 1690 A concrete subclass of :class:`tzinfo` may need to implement the following 1691 methods. Exactly which methods are needed depends on the uses made of aware 1692 :mod:`datetime` objects. If in doubt, simply implement all of them. 1693 1694 1695 .. method:: tzinfo.utcoffset(dt) 1696 1697 Return offset of local time from UTC, as a :class:`timedelta` object that is 1698 positive east of UTC. If local time is 1699 west of UTC, this should be negative. Note that this is intended to be the 1700 total offset from UTC; for example, if a :class:`tzinfo` object represents both 1701 time zone and DST adjustments, :meth:`utcoffset` should return their sum. If 1702 the UTC offset isn't known, return ``None``. Else the value returned must be a 1703 :class:`timedelta` object strictly between ``-timedelta(hours=24)`` and 1704 ``timedelta(hours=24)`` (the magnitude of the offset must be less 1705 than one day). Most implementations of :meth:`utcoffset` will probably look 1706 like one of these two:: 1707 1708 return CONSTANT # fixed-offset class 1709 return CONSTANT + self.dst(dt) # daylight-aware class 1710 1711 If :meth:`utcoffset` does not return ``None``, :meth:`dst` should not return 1712 ``None`` either. 1713 1714 The default implementation of :meth:`utcoffset` raises 1715 :exc:`NotImplementedError`. 1716 1717 .. versionchanged:: 3.7 1718 The UTC offset is not restricted to a whole number of minutes. 1719 1720 1721 .. method:: tzinfo.dst(dt) 1722 1723 Return the daylight saving time (DST) adjustment, as a :class:`timedelta` 1724 object or 1725 ``None`` if DST information isn't known. Return ``timedelta(0)`` if DST is not 1726 in effect. If DST is in effect, return the offset as a :class:`timedelta` object 1727 (see :meth:`utcoffset` for details). Note that DST offset, if applicable, has 1728 already been added to the UTC offset returned by :meth:`utcoffset`, so there's 1729 no need to consult :meth:`dst` unless you're interested in obtaining DST info 1730 separately. For example, :meth:`datetime.timetuple` calls its :attr:`~.datetime.tzinfo` 1731 attribute's :meth:`dst` method to determine how the :attr:`tm_isdst` flag 1732 should be set, and :meth:`tzinfo.fromutc` calls :meth:`dst` to account for 1733 DST changes when crossing time zones. 1734 1735 An instance *tz* of a :class:`tzinfo` subclass that models both standard and 1736 daylight times must be consistent in this sense: 1737 1738 ``tz.utcoffset(dt) - tz.dst(dt)`` 1739 1740 must return the same result for every :class:`.datetime` *dt* with ``dt.tzinfo == 1741 tz`` For sane :class:`tzinfo` subclasses, this expression yields the time 1742 zone's "standard offset", which should not depend on the date or the time, but 1743 only on geographic location. The implementation of :meth:`datetime.astimezone` 1744 relies on this, but cannot detect violations; it's the programmer's 1745 responsibility to ensure it. If a :class:`tzinfo` subclass cannot guarantee 1746 this, it may be able to override the default implementation of 1747 :meth:`tzinfo.fromutc` to work correctly with :meth:`astimezone` regardless. 1748 1749 Most implementations of :meth:`dst` will probably look like one of these two:: 1750 1751 def dst(self, dt): 1752 # a fixed-offset class: doesn't account for DST 1753 return timedelta(0) 1754 1755 or :: 1756 1757 def dst(self, dt): 1758 # Code to set dston and dstoff to the time zone's DST 1759 # transition times based on the input dt.year, and expressed 1760 # in standard local time. Then 1761 1762 if dston <= dt.replace(tzinfo=None) < dstoff: 1763 return timedelta(hours=1) 1764 else: 1765 return timedelta(0) 1766 1767 The default implementation of :meth:`dst` raises :exc:`NotImplementedError`. 1768 1769 .. versionchanged:: 3.7 1770 The DST offset is not restricted to a whole number of minutes. 1771 1772 1773 .. method:: tzinfo.tzname(dt) 1774 1775 Return the time zone name corresponding to the :class:`.datetime` object *dt*, as 1776 a string. Nothing about string names is defined by the :mod:`datetime` module, 1777 and there's no requirement that it mean anything in particular. For example, 1778 "GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" are all 1779 valid replies. Return ``None`` if a string name isn't known. Note that this is 1780 a method rather than a fixed string primarily because some :class:`tzinfo` 1781 subclasses will wish to return different names depending on the specific value 1782 of *dt* passed, especially if the :class:`tzinfo` class is accounting for 1783 daylight time. 1784 1785 The default implementation of :meth:`tzname` raises :exc:`NotImplementedError`. 1786 1787 1788 These methods are called by a :class:`.datetime` or :class:`.time` object, in 1789 response to their methods of the same names. A :class:`.datetime` object passes 1790 itself as the argument, and a :class:`.time` object passes ``None`` as the 1791 argument. A :class:`tzinfo` subclass's methods should therefore be prepared to 1792 accept a *dt* argument of ``None``, or of class :class:`.datetime`. 1793 1794 When ``None`` is passed, it's up to the class designer to decide the best 1795 response. For example, returning ``None`` is appropriate if the class wishes to 1796 say that time objects don't participate in the :class:`tzinfo` protocols. It 1797 may be more useful for ``utcoffset(None)`` to return the standard UTC offset, as 1798 there is no other convention for discovering the standard offset. 1799 1800 When a :class:`.datetime` object is passed in response to a :class:`.datetime` 1801 method, ``dt.tzinfo`` is the same object as *self*. :class:`tzinfo` methods can 1802 rely on this, unless user code calls :class:`tzinfo` methods directly. The 1803 intent is that the :class:`tzinfo` methods interpret *dt* as being in local 1804 time, and not need worry about objects in other timezones. 1805 1806 There is one more :class:`tzinfo` method that a subclass may wish to override: 1807 1808 1809 .. method:: tzinfo.fromutc(dt) 1810 1811 This is called from the default :class:`datetime.astimezone()` 1812 implementation. When called from that, ``dt.tzinfo`` is *self*, and *dt*'s 1813 date and time data are to be viewed as expressing a UTC time. The purpose 1814 of :meth:`fromutc` is to adjust the date and time data, returning an 1815 equivalent datetime in *self*'s local time. 1816 1817 Most :class:`tzinfo` subclasses should be able to inherit the default 1818 :meth:`fromutc` implementation without problems. It's strong enough to handle 1819 fixed-offset time zones, and time zones accounting for both standard and 1820 daylight time, and the latter even if the DST transition times differ in 1821 different years. An example of a time zone the default :meth:`fromutc` 1822 implementation may not handle correctly in all cases is one where the standard 1823 offset (from UTC) depends on the specific date and time passed, which can happen 1824 for political reasons. The default implementations of :meth:`astimezone` and 1825 :meth:`fromutc` may not produce the result you want if the result is one of the 1826 hours straddling the moment the standard offset changes. 1827 1828 Skipping code for error cases, the default :meth:`fromutc` implementation acts 1829 like:: 1830 1831 def fromutc(self, dt): 1832 # raise ValueError error if dt.tzinfo is not self 1833 dtoff = dt.utcoffset() 1834 dtdst = dt.dst() 1835 # raise ValueError if dtoff is None or dtdst is None 1836 delta = dtoff - dtdst # this is self's standard offset 1837 if delta: 1838 dt += delta # convert to standard local time 1839 dtdst = dt.dst() 1840 # raise ValueError if dtdst is None 1841 if dtdst: 1842 return dt + dtdst 1843 else: 1844 return dt 1845 1846 In the following :download:`tzinfo_examples.py 1847 <../includes/tzinfo_examples.py>` file there are some examples of 1848 :class:`tzinfo` classes: 1849 1850 .. literalinclude:: ../includes/tzinfo_examples.py 1851 1852 Note that there are unavoidable subtleties twice per year in a :class:`tzinfo` 1853 subclass accounting for both standard and daylight time, at the DST transition 1854 points. For concreteness, consider US Eastern (UTC -0500), where EDT begins the 1855 minute after 1:59 (EST) on the second Sunday in March, and ends the minute after 1856 1:59 (EDT) on the first Sunday in November:: 1857 1858 UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM 1859 EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM 1860 EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM 1861 1862 start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM 1863 1864 end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM 1865 1866 When DST starts (the "start" line), the local wall clock leaps from 1:59 to 1867 3:00. A wall time of the form 2:MM doesn't really make sense on that day, so 1868 ``astimezone(Eastern)`` won't deliver a result with ``hour == 2`` on the day DST 1869 begins. For example, at the Spring forward transition of 2016, we get 1870 1871 >>> from datetime import datetime, timezone 1872 >>> from tzinfo_examples import HOUR, Eastern 1873 >>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc) 1874 >>> for i in range(4): 1875 ... u = u0 + i*HOUR 1876 ... t = u.astimezone(Eastern) 1877 ... print(u.time(), 'UTC =', t.time(), t.tzname()) 1878 ... 1879 05:00:00 UTC = 00:00:00 EST 1880 06:00:00 UTC = 01:00:00 EST 1881 07:00:00 UTC = 03:00:00 EDT 1882 08:00:00 UTC = 04:00:00 EDT 1883 1884 1885 When DST ends (the "end" line), there's a potentially worse problem: there's an 1886 hour that can't be spelled unambiguously in local wall time: the last hour of 1887 daylight time. In Eastern, that's times of the form 5:MM UTC on the day 1888 daylight time ends. The local wall clock leaps from 1:59 (daylight time) back 1889 to 1:00 (standard time) again. Local times of the form 1:MM are ambiguous. 1890 :meth:`astimezone` mimics the local clock's behavior by mapping two adjacent UTC 1891 hours into the same local hour then. In the Eastern example, UTC times of the 1892 form 5:MM and 6:MM both map to 1:MM when converted to Eastern, but earlier times 1893 have the :attr:`~datetime.fold` attribute set to 0 and the later times have it set to 1. 1894 For example, at the Fall back transition of 2016, we get 1895 1896 >>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc) 1897 >>> for i in range(4): 1898 ... u = u0 + i*HOUR 1899 ... t = u.astimezone(Eastern) 1900 ... print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold) 1901 ... 1902 04:00:00 UTC = 00:00:00 EDT 0 1903 05:00:00 UTC = 01:00:00 EDT 0 1904 06:00:00 UTC = 01:00:00 EST 1 1905 07:00:00 UTC = 02:00:00 EST 0 1906 1907 Note that the :class:`datetime` instances that differ only by the value of the 1908 :attr:`~datetime.fold` attribute are considered equal in comparisons. 1909 1910 Applications that can't bear wall-time ambiguities should explicitly check the 1911 value of the :attr:`~datetime.fold` attribute or avoid using hybrid 1912 :class:`tzinfo` subclasses; there are no ambiguities when using :class:`timezone`, 1913 or any other fixed-offset :class:`tzinfo` subclass (such as a class representing 1914 only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)). 1915 1916 .. seealso:: 1917 1918 `dateutil.tz <https://dateutil.readthedocs.io/en/stable/tz.html>`_ 1919 The standard library has :class:`timezone` class for handling arbitrary 1920 fixed offsets from UTC and :attr:`timezone.utc` as UTC timezone instance. 1921 1922 *dateutil.tz* library brings the *IANA timezone database* (also known as the 1923 Olson database) to Python and its usage is recommended. 1924 1925 `IANA timezone database <https://www.iana.org/time-zones>`_ 1926 The Time Zone Database (often called tz, tzdata or zoneinfo) contains code and 1927 data that represent the history of local time for many representative 1928 locations around the globe. It is updated periodically to reflect changes 1929 made by political bodies to time zone boundaries, UTC offsets, and 1930 daylight-saving rules. 1931 1932 1933 .. _datetime-timezone: 1934 1935 :class:`timezone` Objects 1936 -------------------------- 1937 1938 The :class:`timezone` class is a subclass of :class:`tzinfo`, each 1939 instance of which represents a timezone defined by a fixed offset from 1940 UTC. Note that objects of this class cannot be used to represent 1941 timezone information in the locations where different offsets are used 1942 in different days of the year or where historical changes have been 1943 made to civil time. 1944 1945 1946 .. class:: timezone(offset, name=None) 1947 1948 The *offset* argument must be specified as a :class:`timedelta` 1949 object representing the difference between the local time and UTC. It must 1950 be strictly between ``-timedelta(hours=24)`` and 1951 ``timedelta(hours=24)``, otherwise :exc:`ValueError` is raised. 1952 1953 The *name* argument is optional. If specified it must be a string that 1954 will be used as the value returned by the :meth:`datetime.tzname` method. 1955 1956 .. versionadded:: 3.2 1957 1958 .. versionchanged:: 3.7 1959 The UTC offset is not restricted to a whole number of minutes. 1960 1961 1962 .. method:: timezone.utcoffset(dt) 1963 1964 Return the fixed value specified when the :class:`timezone` instance is 1965 constructed. The *dt* argument is ignored. The return value is a 1966 :class:`timedelta` instance equal to the difference between the 1967 local time and UTC. 1968 1969 .. versionchanged:: 3.7 1970 The UTC offset is not restricted to a whole number of minutes. 1971 1972 .. method:: timezone.tzname(dt) 1973 1974 Return the fixed value specified when the :class:`timezone` instance 1975 is constructed. If *name* is not provided in the constructor, the 1976 name returned by ``tzname(dt)`` is generated from the value of the 1977 ``offset`` as follows. If *offset* is ``timedelta(0)``, the name 1978 is "UTC", otherwise it is a string 'UTCHH:MM', where is the sign 1979 of ``offset``, HH and MM are two digits of ``offset.hours`` and 1980 ``offset.minutes`` respectively. 1981 1982 .. versionchanged:: 3.6 1983 Name generated from ``offset=timedelta(0)`` is now plain 'UTC', not 1984 'UTC+00:00'. 1985 1986 1987 .. method:: timezone.dst(dt) 1988 1989 Always returns ``None``. 1990 1991 .. method:: timezone.fromutc(dt) 1992 1993 Return ``dt + offset``. The *dt* argument must be an aware 1994 :class:`.datetime` instance, with ``tzinfo`` set to ``self``. 1995 1996 Class attributes: 1997 1998 .. attribute:: timezone.utc 1999 2000 The UTC timezone, ``timezone(timedelta(0))``. 2001 2002 2003 .. index:: 2004 single: % (percent); datetime format 2005 2006 .. _strftime-strptime-behavior: 2007 2008 :meth:`strftime` and :meth:`strptime` Behavior 2009 ---------------------------------------------- 2010 2011 :class:`date`, :class:`.datetime`, and :class:`.time` objects all support a 2012 ``strftime(format)`` method, to create a string representing the time under the 2013 control of an explicit format string. Broadly speaking, ``d.strftime(fmt)`` 2014 acts like the :mod:`time` module's ``time.strftime(fmt, d.timetuple())`` 2015 although not all objects support a :meth:`timetuple` method. 2016 2017 Conversely, the :meth:`datetime.strptime` class method creates a 2018 :class:`.datetime` object from a string representing a date and time and a 2019 corresponding format string. ``datetime.strptime(date_string, format)`` is 2020 equivalent to ``datetime(*(time.strptime(date_string, format)[0:6]))``, except 2021 when the format includes sub-second components or timezone offset information, 2022 which are supported in ``datetime.strptime`` but are discarded by ``time.strptime``. 2023 2024 For :class:`.time` objects, the format codes for year, month, and day should not 2025 be used, as time objects have no such values. If they're used anyway, ``1900`` 2026 is substituted for the year, and ``1`` for the month and day. 2027 2028 For :class:`date` objects, the format codes for hours, minutes, seconds, and 2029 microseconds should not be used, as :class:`date` objects have no such 2030 values. If they're used anyway, ``0`` is substituted for them. 2031 2032 The full set of format codes supported varies across platforms, because Python 2033 calls the platform C library's :func:`strftime` function, and platform 2034 variations are common. To see the full set of format codes supported on your 2035 platform, consult the :manpage:`strftime(3)` documentation. 2036 2037 For the same reason, handling of format strings containing Unicode code points 2038 that can't be represented in the charset of the current locale is also 2039 platform-dependent. On some platforms such code points are preserved intact in 2040 the output, while on others ``strftime`` may raise :exc:`UnicodeError` or return 2041 an empty string instead. 2042 2043 The following is a list of all the format codes that the C standard (1989 2044 version) requires, and these work on all platforms with a standard C 2045 implementation. Note that the 1999 version of the C standard added additional 2046 format codes. 2047 2048 +-----------+--------------------------------+------------------------+-------+ 2049 | Directive | Meaning | Example | Notes | 2050 +===========+================================+========================+=======+ 2051 | ``%a`` | Weekday as locale's || Sun, Mon, ..., Sat | \(1) | 2052 | | abbreviated name. | (en_US); | | 2053 | | || So, Mo, ..., Sa | | 2054 | | | (de_DE) | | 2055 +-----------+--------------------------------+------------------------+-------+ 2056 | ``%A`` | Weekday as locale's full name. || Sunday, Monday, ..., | \(1) | 2057 | | | Saturday (en_US); | | 2058 | | || Sonntag, Montag, ..., | | 2059 | | | Samstag (de_DE) | | 2060 +-----------+--------------------------------+------------------------+-------+ 2061 | ``%w`` | Weekday as a decimal number, | 0, 1, ..., 6 | | 2062 | | where 0 is Sunday and 6 is | | | 2063 | | Saturday. | | | 2064 +-----------+--------------------------------+------------------------+-------+ 2065 | ``%d`` | Day of the month as a | 01, 02, ..., 31 | | 2066 | | zero-padded decimal number. | | | 2067 +-----------+--------------------------------+------------------------+-------+ 2068 | ``%b`` | Month as locale's abbreviated || Jan, Feb, ..., Dec | \(1) | 2069 | | name. | (en_US); | | 2070 | | || Jan, Feb, ..., Dez | | 2071 | | | (de_DE) | | 2072 +-----------+--------------------------------+------------------------+-------+ 2073 | ``%B`` | Month as locale's full name. || January, February, | \(1) | 2074 | | | ..., December (en_US);| | 2075 | | || Januar, Februar, ..., | | 2076 | | | Dezember (de_DE) | | 2077 +-----------+--------------------------------+------------------------+-------+ 2078 | ``%m`` | Month as a zero-padded | 01, 02, ..., 12 | | 2079 | | decimal number. | | | 2080 +-----------+--------------------------------+------------------------+-------+ 2081 | ``%y`` | Year without century as a | 00, 01, ..., 99 | | 2082 | | zero-padded decimal number. | | | 2083 +-----------+--------------------------------+------------------------+-------+ 2084 | ``%Y`` | Year with century as a decimal | 0001, 0002, ..., 2013, | \(2) | 2085 | | number. | 2014, ..., 9998, 9999 | | 2086 +-----------+--------------------------------+------------------------+-------+ 2087 | ``%H`` | Hour (24-hour clock) as a | 00, 01, ..., 23 | | 2088 | | zero-padded decimal number. | | | 2089 +-----------+--------------------------------+------------------------+-------+ 2090 | ``%I`` | Hour (12-hour clock) as a | 01, 02, ..., 12 | | 2091 | | zero-padded decimal number. | | | 2092 +-----------+--------------------------------+------------------------+-------+ 2093 | ``%p`` | Locale's equivalent of either || AM, PM (en_US); | \(1), | 2094 | | AM or PM. || am, pm (de_DE) | \(3) | 2095 +-----------+--------------------------------+------------------------+-------+ 2096 | ``%M`` | Minute as a zero-padded | 00, 01, ..., 59 | | 2097 | | decimal number. | | | 2098 +-----------+--------------------------------+------------------------+-------+ 2099 | ``%S`` | Second as a zero-padded | 00, 01, ..., 59 | \(4) | 2100 | | decimal number. | | | 2101 +-----------+--------------------------------+------------------------+-------+ 2102 | ``%f`` | Microsecond as a decimal | 000000, 000001, ..., | \(5) | 2103 | | number, zero-padded on the | 999999 | | 2104 | | left. | | | 2105 +-----------+--------------------------------+------------------------+-------+ 2106 | ``%z`` | UTC offset in the form | (empty), +0000, | \(6) | 2107 | | HHMM[SS[.ffffff]] (empty | -0400, +1030, | | 2108 | | string if the object is | +063415, | | 2109 | | naive). | -030712.345216 | | 2110 +-----------+--------------------------------+------------------------+-------+ 2111 | ``%Z`` | Time zone name (empty string | (empty), UTC, EST, CST | | 2112 | | if the object is naive). | | | 2113 +-----------+--------------------------------+------------------------+-------+ 2114 | ``%j`` | Day of the year as a | 001, 002, ..., 366 | | 2115 | | zero-padded decimal number. | | | 2116 +-----------+--------------------------------+------------------------+-------+ 2117 | ``%U`` | Week number of the year | 00, 01, ..., 53 | \(7) | 2118 | | (Sunday as the first day of | | | 2119 | | the week) as a zero padded | | | 2120 | | decimal number. All days in a | | | 2121 | | new year preceding the first | | | 2122 | | Sunday are considered to be in | | | 2123 | | week 0. | | | 2124 +-----------+--------------------------------+------------------------+-------+ 2125 | ``%W`` | Week number of the year | 00, 01, ..., 53 | \(7) | 2126 | | (Monday as the first day of | | | 2127 | | the week) as a decimal number. | | | 2128 | | All days in a new year | | | 2129 | | preceding the first Monday | | | 2130 | | are considered to be in | | | 2131 | | week 0. | | | 2132 +-----------+--------------------------------+------------------------+-------+ 2133 | ``%c`` | Locale's appropriate date and || Tue Aug 16 21:30:00 | \(1) | 2134 | | time representation. | 1988 (en_US); | | 2135 | | || Di 16 Aug 21:30:00 | | 2136 | | | 1988 (de_DE) | | 2137 +-----------+--------------------------------+------------------------+-------+ 2138 | ``%x`` | Locale's appropriate date || 08/16/88 (None); | \(1) | 2139 | | representation. || 08/16/1988 (en_US); | | 2140 | | || 16.08.1988 (de_DE) | | 2141 +-----------+--------------------------------+------------------------+-------+ 2142 | ``%X`` | Locale's appropriate time || 21:30:00 (en_US); | \(1) | 2143 | | representation. || 21:30:00 (de_DE) | | 2144 +-----------+--------------------------------+------------------------+-------+ 2145 | ``%%`` | A literal ``'%'`` character. | % | | 2146 +-----------+--------------------------------+------------------------+-------+ 2147 2148 Several additional directives not required by the C89 standard are included for 2149 convenience. These parameters all correspond to ISO 8601 date values. These 2150 may not be available on all platforms when used with the :meth:`strftime` 2151 method. The ISO 8601 year and ISO 8601 week directives are not interchangeable 2152 with the year and week number directives above. Calling :meth:`strptime` with 2153 incomplete or ambiguous ISO 8601 directives will raise a :exc:`ValueError`. 2154 2155 +-----------+--------------------------------+------------------------+-------+ 2156 | Directive | Meaning | Example | Notes | 2157 +===========+================================+========================+=======+ 2158 | ``%G`` | ISO 8601 year with century | 0001, 0002, ..., 2013, | \(8) | 2159 | | representing the year that | 2014, ..., 9998, 9999 | | 2160 | | contains the greater part of | | | 2161 | | the ISO week (``%V``). | | | 2162 +-----------+--------------------------------+------------------------+-------+ 2163 | ``%u`` | ISO 8601 weekday as a decimal | 1, 2, ..., 7 | | 2164 | | number where 1 is Monday. | | | 2165 +-----------+--------------------------------+------------------------+-------+ 2166 | ``%V`` | ISO 8601 week as a decimal | 01, 02, ..., 53 | \(8) | 2167 | | number with Monday as | | | 2168 | | the first day of the week. | | | 2169 | | Week 01 is the week containing | | | 2170 | | Jan 4. | | | 2171 +-----------+--------------------------------+------------------------+-------+ 2172 2173 .. versionadded:: 3.6 2174 ``%G``, ``%u`` and ``%V`` were added. 2175 2176 Notes: 2177 2178 (1) 2179 Because the format depends on the current locale, care should be taken when 2180 making assumptions about the output value. Field orderings will vary (for 2181 example, "month/day/year" versus "day/month/year"), and the output may 2182 contain Unicode characters encoded using the locale's default encoding (for 2183 example, if the current locale is ``ja_JP``, the default encoding could be 2184 any one of ``eucJP``, ``SJIS``, or ``utf-8``; use :meth:`locale.getlocale` 2185 to determine the current locale's encoding). 2186 2187 (2) 2188 The :meth:`strptime` method can parse years in the full [1, 9999] range, but 2189 years < 1000 must be zero-filled to 4-digit width. 2190 2191 .. versionchanged:: 3.2 2192 In previous versions, :meth:`strftime` method was restricted to 2193 years >= 1900. 2194 2195 .. versionchanged:: 3.3 2196 In version 3.2, :meth:`strftime` method was restricted to 2197 years >= 1000. 2198 2199 (3) 2200 When used with the :meth:`strptime` method, the ``%p`` directive only affects 2201 the output hour field if the ``%I`` directive is used to parse the hour. 2202 2203 (4) 2204 Unlike the :mod:`time` module, the :mod:`datetime` module does not support 2205 leap seconds. 2206 2207 (5) 2208 When used with the :meth:`strptime` method, the ``%f`` directive 2209 accepts from one to six digits and zero pads on the right. ``%f`` is 2210 an extension to the set of format characters in the C standard (but 2211 implemented separately in datetime objects, and therefore always 2212 available). 2213 2214 (6) 2215 For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty 2216 strings. 2217 2218 For an aware object: 2219 2220 ``%z`` 2221 :meth:`utcoffset` is transformed into a string of the form 2222 HHMM[SS[.ffffff]], where HH is a 2-digit string giving the number of UTC 2223 offset hours, MM is a 2-digit string giving the number of UTC offset 2224 minutes, SS is a 2-digit string giving the number of UTC offset 2225 seconds and ffffff is a 6-digit string giving the number of UTC 2226 offset microseconds. The ffffff part is omitted when the offset is a 2227 whole number of seconds and both the ffffff and the SS part is omitted 2228 when the offset is a whole number of minutes. For example, if 2229 :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is 2230 replaced with the string ``'-0330'``. 2231 2232 .. versionchanged:: 3.7 2233 The UTC offset is not restricted to a whole number of minutes. 2234 2235 .. versionchanged:: 3.7 2236 When the ``%z`` directive is provided to the :meth:`strptime` method, 2237 the UTC offsets can have a colon as a separator between hours, minutes 2238 and seconds. 2239 For example, ``'+01:00:00'`` will be parsed as an offset of one hour. 2240 In addition, providing ``'Z'`` is identical to ``'+00:00'``. 2241 2242 ``%Z`` 2243 If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty 2244 string. Otherwise ``%Z`` is replaced by the returned value, which must 2245 be a string. 2246 2247 .. versionchanged:: 3.2 2248 When the ``%z`` directive is provided to the :meth:`strptime` method, an 2249 aware :class:`.datetime` object will be produced. The ``tzinfo`` of the 2250 result will be set to a :class:`timezone` instance. 2251 2252 (7) 2253 When used with the :meth:`strptime` method, ``%U`` and ``%W`` are only used 2254 in calculations when the day of the week and the calendar year (``%Y``) 2255 are specified. 2256 2257 (8) 2258 Similar to ``%U`` and ``%W``, ``%V`` is only used in calculations when the 2259 day of the week and the ISO year (``%G``) are specified in a 2260 :meth:`strptime` format string. Also note that ``%G`` and ``%Y`` are not 2261 interchangeable. 2262 2263 .. rubric:: Footnotes 2264 2265 .. [#] If, that is, we ignore the effects of Relativity 2266
