Lines Matching +full:not +full:- +full:date
1 :mod:`datetime` --- Basic date and time types
5 :synopsis: Basic date and time types.
15 both simple and complex ways. While date and time arithmetic is supported, the
20 There are two kinds of date and time objects: "naive" and "aware".
25 is used to represent a specific moment in time that is not open to
28 A naive object does not contain enough information to unambiguously locate
29 itself relative to other date/time objects. Whether a naive object represents
50 The smallest year number allowed in a :class:`date` or :class:`.datetime` object.
56 The largest year number allowed in a :class:`date` or :class:`.datetime` object.
70 ---------------
72 .. class:: date
75 An idealized naive date, assuming the current Gregorian calendar always was, and
92 A combination of a date and a time. Attributes: :attr:`year`, :attr:`month`,
100 A duration expressing the difference between two :class:`date`, :class:`.time`,
114 Objects of the :class:`date` type are always naive.
117 A :class:`.datetime` object *d* is aware if ``d.tzinfo`` is not ``None`` and
118 ``d.tzinfo.utcoffset(d)`` does not return ``None``. If ``d.tzinfo`` is
119 ``None``, or if ``d.tzinfo`` is not ``None`` but ``d.tzinfo.utcoffset(d)``
121 if ``t.tzinfo`` is not ``None`` and ``t.tzinfo.utcoffset(None)`` does not return
133 date
137 .. _datetime-timedelta:
140 --------------------------
163 * ``-999999999 <= days <= 999999999``
177 >>> d = timedelta(microseconds=-1)
179 (-1, 86399, 999999)
186 The most negative :class:`timedelta` object, ``timedelta(-999999999)``.
197 The smallest possible difference between non-equal :class:`timedelta` objects,
200 Note that, because of normalization, ``timedelta.max`` > ``-timedelta.min``.
201 ``-timedelta.max`` is not representable as a :class:`timedelta` object.
203 Instance attributes (read-only):
205 +------------------+--------------------------------------------+
208 | ``days`` | Between -999999999 and 999999999 inclusive |
209 +------------------+--------------------------------------------+
211 +------------------+--------------------------------------------+
213 +------------------+--------------------------------------------+
219 +--------------------------------+-----------------------------------------------+
222 | ``t1 = t2 + t3`` | Sum of *t2* and *t3*. Afterwards *t1*-*t2* == |
223 | | *t3* and *t1*-*t3* == *t2* are true. (1) |
224 +--------------------------------+-----------------------------------------------+
225 | ``t1 = t2 - t3`` | Difference of *t2* and *t3*. Afterwards *t1* |
226 | | == *t2* - *t3* and *t2* == *t1* + *t3* are |
228 +--------------------------------+-----------------------------------------------+
232 +--------------------------------+-----------------------------------------------+
233 | | In general, *t1* \* i == *t1* \* (i-1) + *t1* |
235 +--------------------------------+-----------------------------------------------+
238 +--------------------------------+-----------------------------------------------+
241 +--------------------------------+-----------------------------------------------+
242 | ``-t1`` | equivalent to :class:`timedelta`\ |
243 | | (-*t1.days*, -*t1.seconds*, |
244 | | -*t1.microseconds*), and to *t1*\* -1. (1)(4) |
245 +--------------------------------+-----------------------------------------------+
247 | | to -*t* when ``t.days < 0``. (2) |
248 +--------------------------------+-----------------------------------------------+
252 +--------------------------------+-----------------------------------------------+
256 +--------------------------------+-----------------------------------------------+
270 -*timedelta.max* is not representable as a :class:`timedelta` object.
277 >>> timedelta(hours=-5)
278 datetime.timedelta(-1, 68400)
280 -1 day, 19:00:00
283 certain additions and subtractions with :class:`date` and :class:`.datetime`
288 smaller timedelta. In order to stop mixed-type comparisons from falling back to
325 >>> nine_years = ten_years - year
331 >>> abs(three_years - ten_years) == 2 * three_years + year
335 .. _datetime-date:
337 :class:`date` Objects
338 ---------------------
340 A :class:`date` object represents a date (year, month and day) in an idealized
350 .. class:: date(year, month, day)
364 .. classmethod:: date.today()
366 Return the current local date. This is equivalent to
367 ``date.fromtimestamp(time.time())``.
370 .. classmethod:: date.fromtimestamp(timestamp)
372 Return the local date corresponding to the POSIX timestamp, such as is returned
376 that on non-POSIX systems that include leap seconds in their notion of a
380 .. classmethod:: date.fromordinal(ordinal)
382 Return the date corresponding to the proleptic Gregorian ordinal, where January
384 date.max.toordinal()``. For any date *d*, ``date.fromordinal(d.toordinal()) ==
390 .. attribute:: date.min
392 The earliest representable date, ``date(MINYEAR, 1, 1)``.
395 .. attribute:: date.max
397 The latest representable date, ``date(MAXYEAR, 12, 31)``.
400 .. attribute:: date.resolution
402 The smallest possible difference between non-equal date objects,
406 Instance attributes (read-only):
408 .. attribute:: date.year
413 .. attribute:: date.month
418 .. attribute:: date.day
425 +-------------------------------+----------------------------------------------+
430 +-------------------------------+----------------------------------------------+
431 | ``date2 = date1 - timedelta`` | Computes *date2* such that ``date2 + |
433 +-------------------------------+----------------------------------------------+
434 | ``timedelta = date1 - date2`` | \(3) |
435 +-------------------------------+----------------------------------------------+
438 +-------------------------------+----------------------------------------------+
444 ``timedelta.days < 0``. Afterward ``date2 - date1 == timedelta.days``.
450 This isn't quite equivalent to date1 + (-timedelta), because -timedelta in
451 isolation can overflow in cases where date1 - timedelta does not.
461 default scheme of comparing object addresses, date comparison normally raises
462 :exc:`TypeError` if the other comparand isn't also a :class:`date` object.
464 :meth:`timetuple` attribute. This hook gives other kinds of date objects a
465 chance at implementing mixed-type comparison. If not, when a :class:`date`
470 Dates can be used as dictionary keys. In Boolean contexts, all :class:`date`
475 .. method:: date.replace(year, month, day)
477 Return a date with the same value, except for those parameters given new
479 date(2002, 12, 31)``, then ``d.replace(day=26) == date(2002, 12, 26)``.
482 .. method:: date.timetuple()
485 The hours, minutes and seconds are 0, and the DST flag is -1. ``d.timetuple()``
487 d.weekday(), yday, -1))``, where ``yday = d.toordinal() - date(d.year, 1,
492 .. method:: date.toordinal()
494 Return the proleptic Gregorian ordinal of the date, where January 1 of year 1
495 has ordinal 1. For any :class:`date` object *d*,
496 ``date.fromordinal(d.toordinal()) == d``.
499 .. method:: date.weekday()
502 For example, ``date(2002, 12, 4).weekday() == 2``, a Wednesday. See also
506 .. method:: date.isoweekday()
509 For example, ``date(2002, 12, 4).isoweekday() == 3``, a Wednesday. See also
513 .. method:: date.isocalendar()
515 Return a 3-tuple, (ISO year, ISO week number, ISO weekday).
528 ``date(2003, 12, 29).isocalendar() == (2004, 1, 1)`` and ``date(2004, 1,
532 .. method:: date.isoformat()
534 Return a string representing the date in ISO 8601 format, 'YYYY-MM-DD'. For
535 example, ``date(2002, 12, 4).isoformat() == '2002-12-04'``.
538 .. method:: date.__str__()
540 For a date *d*, ``str(d)`` is equivalent to ``d.isoformat()``.
543 .. method:: date.ctime()
545 Return a string representing the date, for example ``date(2002, 12,
549 :meth:`date.ctime` does not invoke) conforms to the C standard.
552 .. method:: date.strftime(format)
554 Return a string representing the date, controlled by an explicit format string.
557 :ref:`strftime-strptime-behavior`.
560 .. method:: date.__format__(format)
562 Same as :meth:`.date.strftime`. This makes it possible to specify a format
563 string for a :class:`.date` object when using :meth:`str.format`.
564 See section :ref:`strftime-strptime-behavior`.
570 >>> from datetime import date
571 >>> today = date.today()
573 datetime.date(2007, 12, 5)
574 >>> today == date.fromtimestamp(time.time())
576 >>> my_birthday = date(today.year, 6, 24)
580 datetime.date(2008, 6, 24)
581 >>> time_to_birthday = abs(my_birthday - today)
585 Example of working with :class:`date`:
589 >>> from datetime import date
590 >>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
592 datetime.date(2002, 3, 11)
604 -1
612 '2002-03-11'
621 .. _datetime-datetime:
624 --------------------------
627 from a :class:`date` object and a :class:`.time` object. Like a :class:`date`
661 Return the current local date and time. If optional argument *tz* is ``None``
662 or not specified, this is like :meth:`today`, but, if possible, supplies more
667 If *tz* is not ``None``, it must be an instance of a :class:`tzinfo` subclass, and the
668 current date and time are converted to *tz*’s time zone. In this case the
675 Return the current UTC date and time, with :attr:`.tzinfo` ``None``. This is like
676 :meth:`now`, but returns the current UTC date and time, as a naive
682 Return the local date and time corresponding to the POSIX timestamp, such as is
683 returned by :func:`time.time`. If optional argument *tz* is ``None`` or not
684 specified, the timestamp is converted to the platform's local date and time, and
687 If *tz* is not ``None``, it must be an instance of a :class:`tzinfo` subclass, and the
695 1970 through 2038. Note that on non-POSIX systems that include leap seconds in
718 .. classmethod:: datetime.combine(date, time)
720 Return a new :class:`.datetime` object whose date components are equal to the
721 given :class:`date` object's, and whose time components and :attr:`.tzinfo`
724 ``d == datetime.combine(d.date(), d.timetz())``. If date is a
736 :ref:`strftime-strptime-behavior`.
757 The smallest possible difference between non-equal :class:`.datetime` objects,
761 Instance attributes (read-only):
806 +---------------------------------------+--------------------------------+
810 +---------------------------------------+--------------------------------+
811 | ``datetime2 = datetime1 - timedelta`` | \(2) |
812 +---------------------------------------+--------------------------------+
813 | ``timedelta = datetime1 - datetime2`` | \(3) |
814 +---------------------------------------+--------------------------------+
817 +---------------------------------------+--------------------------------+
823 datetime2 - datetime1 == timedelta after. :exc:`OverflowError` is raised if
832 This isn't quite equivalent to datetime1 + (-timedelta), because -timedelta
833 in isolation can overflow in cases where datetime1 - timedelta does not.
845 If both are aware and have different :attr:`~.datetime.tzinfo` attributes, ``a-b`` acts
847 result is ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None)
848 - b.utcoffset())`` except that the implementation never overflows.
867 :meth:`timetuple` attribute. This hook gives other kinds of date objects a
868 chance at implementing mixed-type comparison. If not, when a :class:`.datetime`
878 .. method:: datetime.date()
880 Return :class:`date` object with same year, month and day.
900 datetime with no conversion of date and time data.
906 adjusting the date and time data so the result is the same UTC time as
910 :meth:`utcoffset` and :meth:`dst` methods must not return ``None``. *self* must
911 be aware (``self.tzinfo`` must not be ``None``, and ``self.utcoffset()`` must
912 not return ``None``).
915 adjustment of date or time data is performed. Else the result is local
917 ``astz = dt.astimezone(tz)``, ``astz - astz.utcoffset()`` will usually have
918 the same date and time data as ``dt - dt.utcoffset()``. The discussion
924 adjustment of date and time data, use ``dt.replace(tzinfo=tz)``. If you
926 conversion of date and time data, use ``dt.replace(tzinfo=None)``.
936 utc = (self - self.utcoffset()).replace(tzinfo=tz)
969 d.toordinal() - date(d.year, 1, 1).toordinal() + 1`` is the day number within
972 ``None`` or :meth:`dst` returns ``None``, :attr:`tm_isdst` is set to ``-1``;
973 else if :meth:`dst` returns a non-zero value, :attr:`tm_isdst` is set to ``1``;
986 :attr:`tm_year` member may be :const:`MINYEAR`\ -1 or :const:`MAXYEAR`\ +1, if
993 Return the proleptic Gregorian ordinal of the date. The same as
994 ``self.date().toordinal()``.
1000 The same as ``self.date().weekday()``. See also :meth:`isoweekday`.
1006 The same as ``self.date().isoweekday()``. See also :meth:`weekday`,
1012 Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The same as
1013 ``self.date().isocalendar()``.
1018 Return a string representing the date and time in ISO 8601 format,
1019 YYYY-MM-DDTHH:MM:SS.mmmmmm or, if :attr:`microsecond` is 0,
1020 YYYY-MM-DDTHH:MM:SS
1022 If :meth:`utcoffset` does not return ``None``, a 6-character string is
1024 YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM or, if :attr:`microsecond` is 0
1025 YYYY-MM-DDTHH:MM:SS+HH:MM
1027 The optional argument *sep* (default ``'T'``) is a one-character separator,
1028 placed between the date and time portions of the result. For example,
1032 ... def utcoffset(self, dt): return timedelta(minutes=-399)
1035 '2002-12-25 00:00:00-06:39'
1046 Return a string representing the date and time, for example ``datetime(2002, 12,
1050 :meth:`datetime.ctime` does not invoke) conforms to the C standard.
1055 Return a string representing the date and time, controlled by an explicit format
1057 :ref:`strftime-strptime-behavior`.
1064 See section :ref:`strftime-strptime-behavior`.
1071 >>> from datetime import datetime, date, time
1073 >>> d = date(2005, 7, 14)
1099 -1 # dst - method tzinfo.dst() returned None
1100 >>> # Date in ISO format
1123 ... self.dston = d - timedelta(days=d.weekday() + 1)
1125 ... self.dstoff = d - timedelta(days=d.weekday() + 1)
1138 ... self.dston = d - timedelta(days=d.weekday() + 1)
1140 ... self.dstoff = d - timedelta(days=d.weekday() + 1)
1171 .. _datetime-time:
1174 ----------------------
1208 The smallest possible difference between non-equal :class:`.time` objects,
1210 :class:`.time` objects is not supported.
1213 Instance attributes (read-only):
1250 to stop mixed-type comparisons from falling back to the default comparison by
1261 ``0`` if that's ``None``), the result is non-zero.
1277 self.microsecond is 0, HH:MM:SS If :meth:`utcoffset` does not return ``None``, a
1278 6-character string is appended, giving the UTC offset in (signed) hours and
1291 :ref:`strftime-strptime-behavior`.
1298 See section :ref:`strftime-strptime-behavior`.
1351 .. _datetime-tzinfo:
1354 -----------------------
1358 This is an abstract base class, meaning that this class should not be
1361 :class:`.datetime` methods you use. The :mod:`datetime` module does not supply
1368 zone, and DST offset, all relative to a date or time object passed to them.
1372 pickled but possibly not unpickled again. This is a technical requirement that
1388 -1439 to 1439 inclusive (1440 = 24\*60; the magnitude of the offset must be less
1392 return CONSTANT # fixed-offset class
1393 return CONSTANT + self.dst(dt) # daylight-aware class
1395 If :meth:`utcoffset` does not return ``None``, :meth:`dst` should not return
1405 ``None`` if DST information isn't known. Return ``timedelta(0)`` if DST is not
1418 ``tz.utcoffset(dt) - tz.dst(dt)``
1422 zone's "standard offset", which should not depend on the date or the time, but
1432 # a fixed-offset class: doesn't account for DST
1455 "GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" are all
1481 time, and not need worry about objects in other timezones.
1490 date and time data are to be viewed as expressing a UTC time. The purpose
1491 of :meth:`fromutc` is to adjust the date and time data, returning an
1496 fixed-offset time zones, and time zones accounting for both standard and
1499 implementation may not handle correctly in all cases is one where the standard
1500 offset (from UTC) depends on the specific date and time passed, which can happen
1502 :meth:`fromutc` may not produce the result you want if the result is one of the
1509 # raise ValueError error if dt.tzinfo is not self
1513 delta = dtoff - dtdst # this is self's standard offset
1525 .. literalinclude:: ../includes/tzinfo-examples.py
1530 points. For concreteness, consider US Eastern (UTC -0500), where EDT begins the
1564 other fixed-offset :class:`tzinfo` subclass (such as a class representing only
1565 EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).
1571 there exists a third-party library which brings the *IANA timezone
1574 *pytz* contains up-to-date information and its usage is recommended.
1576 `IANA timezone database <https://www.iana.org/time-zones>`_
1581 daylight-saving rules.
1583 .. _strftime-strptime-behavior:
1586 ----------------------------------------------
1588 :class:`date`, :class:`.datetime`, and :class:`.time` objects all support a
1592 although not all objects support a :meth:`timetuple` method.
1595 :class:`.datetime` object from a string representing a date and time and a
1599 For :class:`.time` objects, the format codes for year, month, and day should not
1603 For :class:`date` objects, the format codes for hours, minutes, seconds, and
1604 microseconds should not be used, as :class:`date` objects have no such
1620 +-----------+--------------------------------+------------------------+-------+
1627 +-----------+--------------------------------+------------------------+-------+
1632 +-----------+--------------------------------+------------------------+-------+
1636 +-----------+--------------------------------+------------------------+-------+
1638 | | zero-padded decimal number. | | |
1639 +-----------+--------------------------------+------------------------+-------+
1644 +-----------+--------------------------------+------------------------+-------+
1649 +-----------+--------------------------------+------------------------+-------+
1650 | ``%m`` | Month as a zero-padded | 01, 02, ..., 12 | |
1652 +-----------+--------------------------------+------------------------+-------+
1654 | | zero-padded decimal number. | | |
1655 +-----------+--------------------------------+------------------------+-------+
1658 +-----------+--------------------------------+------------------------+-------+
1659 | ``%H`` | Hour (24-hour clock) as a | 00, 01, ..., 23 | |
1660 | | zero-padded decimal number. | | |
1661 +-----------+--------------------------------+------------------------+-------+
1662 | ``%I`` | Hour (12-hour clock) as a | 01, 02, ..., 12 | |
1663 | | zero-padded decimal number. | | |
1664 +-----------+--------------------------------+------------------------+-------+
1667 +-----------+--------------------------------+------------------------+-------+
1668 | ``%M`` | Minute as a zero-padded | 00, 01, ..., 59 | |
1670 +-----------+--------------------------------+------------------------+-------+
1671 | ``%S`` | Second as a zero-padded | 00, 01, ..., 59 | \(3) |
1673 +-----------+--------------------------------+------------------------+-------+
1675 | | number, zero-padded on the | 999999 | |
1677 +-----------+--------------------------------+------------------------+-------+
1678 | ``%z`` | UTC offset in the form +HHMM | (empty), +0000, -0400, | \(5) |
1679 | | or -HHMM (empty string if the | +1030 | |
1681 +-----------+--------------------------------+------------------------+-------+
1684 +-----------+--------------------------------+------------------------+-------+
1686 | | zero-padded decimal number. | | |
1687 +-----------+--------------------------------+------------------------+-------+
1695 +-----------+--------------------------------+------------------------+-------+
1703 +-----------+--------------------------------+------------------------+-------+
1704 | ``%c`` | Locale's appropriate date and || Tue Aug 16 21:30:00 | \(1) |
1708 +-----------+--------------------------------+------------------------+-------+
1709 | ``%x`` | Locale's appropriate date || 08/16/88 (None); | \(1) |
1712 +-----------+--------------------------------+------------------------+-------+
1715 +-----------+--------------------------------+------------------------+-------+
1717 +-----------+--------------------------------+------------------------+-------+
1727 any one of ``eucJP``, ``SJIS``, or ``utf-8``; use :meth:`locale.getlocale`
1735 Unlike the :mod:`time` module, the :mod:`datetime` module does not support
1753 :meth:`utcoffset` is transformed into a 5-character string of the form
1754 +HHMM or -HHMM, where HH is a 2-digit string giving the number of UTC
1755 offset hours, and MM is a 2-digit string giving the number of UTC offset
1757 ``timedelta(hours=-3, minutes=-30)``, ``%z`` is replaced with the string
1758 ``'-0330'``.