.. XXX what order should the types be discussed in?
-The :mod:`datetime` module supplies classes for manipulating dates and times.
+The :mod:`!datetime` module supplies classes for manipulating dates and times.
While date and time arithmetic is supported, the focus of the implementation is
on efficient attribute extraction for output formatting and manipulation.
time, the time zone name, and whether daylight saving time is in effect.
Only one concrete :class:`tzinfo` class, the :class:`timezone` class, is
-supplied by the :mod:`datetime` module. The :class:`timezone` class can
+supplied by the :mod:`!datetime` module. The :class:`timezone` class can
represent simple timezones with fixed offsets from UTC, such as UTC itself or
North American EST and EDT timezones. Supporting timezones at deeper levels of
detail is up to the application. The rules for time adjustment across the
Constants
---------
-The :mod:`datetime` module exports the following constants:
+The :mod:`!datetime` module exports the following constants:
.. data:: MINYEAR
date2.toordinal()``. Date comparison raises :exc:`TypeError` if
the other comparand isn't also a :class:`date` object. However,
``NotImplemented`` is returned instead if the other comparand has a
- :meth:`timetuple` attribute. This hook gives other kinds of date objects a
+ :attr:`~date.timetuple` attribute. This hook gives other kinds of date objects a
chance at implementing mixed-type comparison. If not, when a :class:`date`
object is compared to an object of a different type, :exc:`TypeError` is raised
unless the comparison is ``==`` or ``!=``. The latter cases return
object addresses, datetime comparison normally raises :exc:`TypeError` if the
other comparand isn't also a :class:`.datetime` object. However,
``NotImplemented`` is returned instead if the other comparand has a
- :meth:`timetuple` attribute. This hook gives other kinds of date objects a
+ :attr:`~.datetime.timetuple` attribute. This hook gives other kinds of date objects a
chance at implementing mixed-type comparison. If not, when a :class:`.datetime`
object is compared to an object of a different type, :exc:`TypeError` is raised
unless the comparison is ``==`` or ``!=``. The latter cases return
where ``yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1``
is the day number within the current year starting with ``1`` for January
- 1st. The :attr:`tm_isdst` flag of the result is set according to the
+ 1st. The :attr:`~time.struct_time.tm_isdst` flag of the result is set according to the
:meth:`dst` method: :attr:`.tzinfo` is ``None`` or :meth:`dst` returns
- ``None``, :attr:`tm_isdst` is set to ``-1``; else if :meth:`dst` returns a
- non-zero value, :attr:`tm_isdst` is set to ``1``; else :attr:`tm_isdst` is
+ ``None``, :attr:`!tm_isdst` is set to ``-1``; else if :meth:`dst` returns a
+ non-zero value, :attr:`!tm_isdst` is set to ``1``; else :attr:`!tm_isdst` is
set to ``0``.
.. method:: datetime.utctimetuple()
If :class:`.datetime` instance *d* is naive, this is the same as
- ``d.timetuple()`` except that :attr:`tm_isdst` is forced to 0 regardless of what
+ ``d.timetuple()`` except that :attr:`~.time.struct_time.tm_isdst` is forced to 0 regardless of what
``d.dst()`` returns. DST is never in effect for a UTC time.
If *d* is aware, *d* is normalized to UTC time, by subtracting
``d.utcoffset()``, and a :class:`time.struct_time` for the
- normalized time is returned. :attr:`tm_isdst` is forced to 0. Note
+ normalized time is returned. :attr:`!tm_isdst` is forced to 0. Note
that an :exc:`OverflowError` may be raised if *d*.year was
``MINYEAR`` or ``MAXYEAR`` and UTC adjustment spills over a year
boundary.
Examples of Usage: :class:`.datetime`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Examples of working with :class:`~datetime.datetime` objects:
+Examples of working with :class:`.datetime` objects:
.. doctest::
comparisons, naive instances are never equal to aware instances.
If both comparands are aware, and have
-the same :attr:`~time.tzinfo` attribute, the common :attr:`~time.tzinfo` attribute is
+the same :attr:`~.time.tzinfo` attribute, the common :attr:`!tzinfo` attribute is
ignored and the base times are compared. If both comparands are aware and
-have different :attr:`~time.tzinfo` attributes, the comparands are first adjusted by
+have different :attr:`!tzinfo` attributes, the comparands are first adjusted by
subtracting their UTC offsets (obtained from ``self.utcoffset()``). In order
to stop mixed-type comparisons from falling back to the default comparison by
object address, when a :class:`.time` object is compared to an object of a
``!=``. The latter cases return :const:`False` or :const:`True`, respectively.
.. versionchanged:: 3.3
- Equality comparisons between aware and naive :class:`~datetime.time` instances
+ Equality comparisons between aware and naive :class:`.time` instances
don't raise :exc:`TypeError`.
In Boolean contexts, a :class:`.time` object is always considered to be true.
You need to derive a concrete subclass, and (at least)
supply implementations of the standard :class:`tzinfo` methods needed by the
- :class:`.datetime` methods you use. The :mod:`datetime` module provides
+ :class:`.datetime` methods you use. The :mod:`!datetime` module provides
:class:`timezone`, a simple concrete subclass of :class:`tzinfo` which can
represent timezones with fixed offset from UTC such as UTC itself or North
American EST and EDT.
A concrete subclass of :class:`tzinfo` may need to implement the following
methods. Exactly which methods are needed depends on the uses made of aware
- :mod:`datetime` objects. If in doubt, simply implement all of them.
+ :mod:`!datetime` objects. If in doubt, simply implement all of them.
.. method:: tzinfo.utcoffset(dt)
already been added to the UTC offset returned by :meth:`utcoffset`, so there's
no need to consult :meth:`dst` unless you're interested in obtaining DST info
separately. For example, :meth:`datetime.timetuple` calls its :attr:`~.datetime.tzinfo`
- attribute's :meth:`dst` method to determine how the :attr:`tm_isdst` flag
+ attribute's :meth:`dst` method to determine how the :attr:`~time.struct_time.tm_isdst` flag
should be set, and :meth:`tzinfo.fromutc` calls :meth:`dst` to account for
DST changes when crossing time zones.
relies on this, but cannot detect violations; it's the programmer's
responsibility to ensure it. If a :class:`tzinfo` subclass cannot guarantee
this, it may be able to override the default implementation of
- :meth:`tzinfo.fromutc` to work correctly with :meth:`astimezone` regardless.
+ :meth:`tzinfo.fromutc` to work correctly with :meth:`~.datetime.astimezone` regardless.
Most implementations of :meth:`dst` will probably look like one of these two::
.. method:: tzinfo.tzname(dt)
Return the time zone name corresponding to the :class:`.datetime` object *dt*, as
- a string. Nothing about string names is defined by the :mod:`datetime` module,
+ a string. Nothing about string names is defined by the :mod:`!datetime` module,
and there's no requirement that it mean anything in particular. For example,
"GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" are all
valid replies. Return ``None`` if a string name isn't known. Note that this is
different years. An example of a time zone the default :meth:`fromutc`
implementation may not handle correctly in all cases is one where the standard
offset (from UTC) depends on the specific date and time passed, which can happen
- for political reasons. The default implementations of :meth:`astimezone` and
+ for political reasons. The default implementations of :meth:`~.datetime.astimezone` and
:meth:`fromutc` may not produce the result you want if the result is one of the
hours straddling the moment the standard offset changes.
daylight time. In Eastern, that's times of the form 5:MM UTC on the day
daylight time ends. The local wall clock leaps from 1:59 (daylight time) back
to 1:00 (standard time) again. Local times of the form 1:MM are ambiguous.
-:meth:`astimezone` mimics the local clock's behavior by mapping two adjacent UTC
+:meth:`~.datetime.astimezone` mimics the local clock's behavior by mapping two adjacent UTC
hours into the same local hour then. In the Eastern example, UTC times of the
form 5:MM and 6:MM both map to 1:MM when converted to Eastern, but earlier times
-have the :attr:`~datetime.fold` attribute set to 0 and the later times have it set to 1.
+have the :attr:`~.datetime.fold` attribute set to 0 and the later times have it set to 1.
For example, at the Fall back transition of 2016, we get::
>>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)
07:00:00 UTC = 02:00:00 EST 0
Note that the :class:`.datetime` instances that differ only by the value of the
-:attr:`~datetime.fold` attribute are considered equal in comparisons.
+:attr:`~.datetime.fold` attribute are considered equal in comparisons.
Applications that can't bear wall-time ambiguities should explicitly check the
-value of the :attr:`~datetime.fold` attribute or avoid using hybrid
+value of the :attr:`~.datetime.fold` attribute or avoid using hybrid
:class:`tzinfo` subclasses; there are no ambiguities when using :class:`timezone`,
or any other fixed-offset :class:`tzinfo` subclass (such as a class representing
only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).
.. seealso::
:mod:`zoneinfo`
- The :mod:`datetime` module has a basic :class:`timezone` class (for
+ The :mod:`!datetime` module has a basic :class:`timezone` class (for
handling arbitrary fixed offsets from UTC) and its :attr:`timezone.utc`
attribute (a UTC timezone instance).
.. _datetime-timezone:
:class:`timezone` Objects
---------------------------
+-------------------------
The :class:`timezone` class is a subclass of :class:`tzinfo`, each
instance of which represents a timezone defined by a fixed offset from
.. _strftime-strptime-behavior:
-:meth:`strftime` and :meth:`strptime` Behavior
-----------------------------------------------
+:meth:`~.datetime.strftime` and :meth:`~.datetime.strptime` Behavior
+--------------------------------------------------------------------
:class:`date`, :class:`.datetime`, and :class:`.time` objects all support a
``strftime(format)`` method, to create a string representing the time under the
:class:`.datetime` object from a string representing a date and time and a
corresponding format string.
-The table below provides a high-level comparison of :meth:`strftime`
-versus :meth:`strptime`:
+The table below provides a high-level comparison of :meth:`~.datetime.strftime`
+versus :meth:`~.datetime.strptime`:
+----------------+--------------------------------------------------------+------------------------------------------------------------------------------+
| | ``strftime`` | ``strptime`` |
.. _format-codes:
-:meth:`strftime` and :meth:`strptime` Format Codes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:meth:`~.datetime.strftime` and :meth:`~.datetime.strptime` Format Codes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These methods accept format codes that can be used to parse and format dates::
| | Jan 4. | | |
+-----------+--------------------------------+------------------------+-------+
-These may not be available on all platforms when used with the :meth:`strftime`
+These may not be available on all platforms when used with the :meth:`~.datetime.strftime`
method. The ISO 8601 year and ISO 8601 week directives are not interchangeable
-with the year and week number directives above. Calling :meth:`strptime` with
+with the year and week number directives above. Calling :meth:`~.datetime.strptime` with
incomplete or ambiguous ISO 8601 directives will raise a :exc:`ValueError`.
The full set of format codes supported varies across platforms, because Python
-calls the platform C library's :func:`strftime` function, and platform
+calls the platform C library's :c:func:`strftime` function, and platform
variations are common. To see the full set of format codes supported on your
platform, consult the :manpage:`strftime(3)` documentation. There are also
differences between platforms in handling of unsupported format specifiers.
Broadly speaking, ``d.strftime(fmt)`` acts like the :mod:`time` module's
``time.strftime(fmt, d.timetuple())`` although not all objects support a
-:meth:`timetuple` method.
+:meth:`~date.timetuple` method.
-For the :meth:`datetime.strptime` class method, the default value is
+For the :meth:`.datetime.strptime` class method, the default value is
``1900-01-01T00:00:00.000``: any components not specified in the format string
will be pulled from the default value. [#]_
contain non-ASCII characters.
(2)
- The :meth:`strptime` method can parse years in the full [1, 9999] range, but
+ The :meth:`~.datetime.strptime` method can parse years in the full [1, 9999] range, but
years < 1000 must be zero-filled to 4-digit width.
.. versionchanged:: 3.2
- In previous versions, :meth:`strftime` method was restricted to
+ In previous versions, :meth:`~.datetime.strftime` method was restricted to
years >= 1900.
.. versionchanged:: 3.3
- In version 3.2, :meth:`strftime` method was restricted to
+ In version 3.2, :meth:`~.datetime.strftime` method was restricted to
years >= 1000.
(3)
- When used with the :meth:`strptime` method, the ``%p`` directive only affects
+ When used with the :meth:`~.datetime.strptime` method, the ``%p`` directive only affects
the output hour field if the ``%I`` directive is used to parse the hour.
(4)
- Unlike the :mod:`time` module, the :mod:`datetime` module does not support
+ Unlike the :mod:`time` module, the :mod:`!datetime` module does not support
leap seconds.
(5)
- When used with the :meth:`strptime` method, the ``%f`` directive
+ When used with the :meth:`~.datetime.strptime` method, the ``%f`` directive
accepts from one to six digits and zero pads on the right. ``%f`` is
an extension to the set of format characters in the C standard (but
implemented separately in datetime objects, and therefore always
For an aware object:
``%z``
- :meth:`utcoffset` is transformed into a string of the form
+ :meth:`~.datetime.utcoffset` is transformed into a string of the form
``±HHMM[SS[.ffffff]]``, where ``HH`` is a 2-digit string giving the number
of UTC offset hours, ``MM`` is a 2-digit string giving the number of UTC
offset minutes, ``SS`` is a 2-digit string giving the number of UTC offset
offset microseconds. The ``ffffff`` part is omitted when the offset is a
whole number of seconds and both the ``ffffff`` and the ``SS`` part is
omitted when the offset is a whole number of minutes. For example, if
- :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is
+ :meth:`~.datetime.utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is
replaced with the string ``'-0330'``.
.. versionchanged:: 3.7
The UTC offset is not restricted to a whole number of minutes.
.. versionchanged:: 3.7
- When the ``%z`` directive is provided to the :meth:`strptime` method,
+ When the ``%z`` directive is provided to the :meth:`~.datetime.strptime` method,
the UTC offsets can have a colon as a separator between hours, minutes
and seconds.
For example, ``'+01:00:00'`` will be parsed as an offset of one hour.
In addition, providing ``'Z'`` is identical to ``'+00:00'``.
``%Z``
- In :meth:`strftime`, ``%Z`` is replaced by an empty string if
- :meth:`tzname` returns ``None``; otherwise ``%Z`` is replaced by the
+ In :meth:`~.datetime.strftime`, ``%Z`` is replaced by an empty string if
+ :meth:`~.datetime.tzname` returns ``None``; otherwise ``%Z`` is replaced by the
returned value, which must be a string.
- :meth:`strptime` only accepts certain values for ``%Z``:
+ :meth:`~.datetime.strptime` only accepts certain values for ``%Z``:
1. any value in ``time.tzname`` for your machine's locale
2. the hard-coded values ``UTC`` and ``GMT``
invalid values.
.. versionchanged:: 3.2
- When the ``%z`` directive is provided to the :meth:`strptime` method, an
+ When the ``%z`` directive is provided to the :meth:`~.datetime.strptime` method, an
aware :class:`.datetime` object will be produced. The ``tzinfo`` of the
result will be set to a :class:`timezone` instance.
(7)
- When used with the :meth:`strptime` method, ``%U`` and ``%W`` are only used
+ When used with the :meth:`~.datetime.strptime` method, ``%U`` and ``%W`` are only used
in calculations when the day of the week and the calendar year (``%Y``)
are specified.
(8)
Similar to ``%U`` and ``%W``, ``%V`` is only used in calculations when the
day of the week and the ISO year (``%G``) are specified in a
- :meth:`strptime` format string. Also note that ``%G`` and ``%Y`` are not
+ :meth:`~.datetime.strptime` format string. Also note that ``%G`` and ``%Y`` are not
interchangeable.
(9)
- When used with the :meth:`strptime` method, the leading zero is optional
+ When used with the :meth:`~.datetime.strptime` method, the leading zero is optional
for formats ``%d``, ``%m``, ``%H``, ``%I``, ``%M``, ``%S``, ``%j``, ``%U``,
``%W``, and ``%V``. Format ``%y`` does require a leading zero.
projects / thirdparty / Python / cpython.git / commitdiff
