Skip to content

C
cpython
Commit 8ff2f50b authored by David Wolever's avatar David Wolever
Browse files
Options

Issue #17701: Improving strftime documentation.

parent 6a92964b
Show whitespace changes
Inline Side-by-side
Showing with 168 additions and 138 deletions
Doc/library/datetime.rst
View file @ 8ff2f50b
...@@ -593,15 +593,17 @@ Instance methods: ...@@ -593,15 +593,17 @@ Instance methods:
.. method:: date.strftime(format) .. method:: date.strftime(format)
Return a string representing the date, controlled by an explicit format string. Return a string representing the date, controlled by an explicit format string.
Format codes referring to hours, minutes or seconds will see 0 values. See Format codes referring to hours, minutes or seconds will see 0 values. For a
section :ref:`strftime-strptime-behavior`. complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
.. method:: date.__format__(format) .. method:: date.__format__(format)
Same as :meth:`.date.strftime`. This makes it possible to specify format Same as :meth:`.date.strftime`. This makes it possible to specify format
string for a :class:`.date` object when using :meth:`str.format`. string for a :class:`.date` object when using :meth:`str.format`. For a
See section :ref:`strftime-strptime-behavior`. complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
Example of counting days to an event:: Example of counting days to an event::
...@@ -793,7 +795,8 @@ Other constructors, all class methods: ...@@ -793,7 +795,8 @@ Other constructors, all class methods:
*format*. This is equivalent to ``datetime(*(time.strptime(date_string, *format*. This is equivalent to ``datetime(*(time.strptime(date_string,
format)[0:6]))``. :exc:`ValueError` is raised if the date_string and format format)[0:6]))``. :exc:`ValueError` is raised if the date_string and format
can't be parsed by :func:`time.strptime` or if it returns a value which isn't a can't be parsed by :func:`time.strptime` or if it returns a value which isn't a
time tuple. See section :ref:`strftime-strptime-behavior`. time tuple. For a complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
...@@ -1160,14 +1163,16 @@ Instance methods: ...@@ -1160,14 +1163,16 @@ Instance methods:
.. method:: datetime.strftime(format) .. method:: datetime.strftime(format)
Return a string representing the date and time, controlled by an explicit format Return a string representing the date and time, controlled by an explicit format
string. See section :ref:`strftime-strptime-behavior`. string. For a complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
.. method:: datetime.__format__(format) .. method:: datetime.__format__(format)
Same as :meth:`.datetime.strftime`. This makes it possible to specify format Same as :meth:`.datetime.strftime`. This makes it possible to specify format
string for a :class:`.datetime` object when using :meth:`str.format`. string for a :class:`.datetime` object when using :meth:`str.format`. For a
See section :ref:`strftime-strptime-behavior`. complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
Examples of working with datetime objects: Examples of working with datetime objects:
...@@ -1399,15 +1404,17 @@ Instance methods: ...@@ -1399,15 +1404,17 @@ Instance methods:
.. method:: time.strftime(format) .. method:: time.strftime(format)
Return a string representing the time, controlled by an explicit format string. Return a string representing the time, controlled by an explicit format
See section :ref:`strftime-strptime-behavior`. string. For a complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
.. method:: time.__format__(format) .. method:: time.__format__(format)
Same as :meth:`.time.strftime`. This makes it possible to specify format string Same as :meth:`.time.strftime`. This makes it possible to specify format string
for a :class:`.time` object when using :meth:`str.format`. for a :class:`.time` object when using :meth:`str.format`. For a
See section :ref:`strftime-strptime-behavior`. complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
.. method:: time.utcoffset() .. method:: time.utcoffset()
...@@ -1773,22 +1780,6 @@ For :class:`date` objects, the format codes for hours, minutes, seconds, and ...@@ -1773,22 +1780,6 @@ For :class:`date` objects, the format codes for hours, minutes, seconds, and
microseconds should not be used, as :class:`date` objects have no such microseconds should not be used, as :class:`date` objects have no such
values. If they're used anyway, ``0`` is substituted for them. values. If they're used anyway, ``0`` is substituted for them.
For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty
strings.
For an aware object:
``%z``
:meth:`utcoffset` is transformed into a 5-character string of the form +HHMM or
-HHMM, where HH is a 2-digit string giving the number of UTC offset hours, and
MM is a 2-digit string giving the number of UTC offset minutes. For example, if
:meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is
replaced with the string ``'-0330'``.
``%Z``
If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty string.
Otherwise ``%Z`` is replaced by the returned value, which must be a string.
The full set of format codes supported varies across platforms, because Python 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 :func:`strftime` function, and platform
variations are common. variations are common.
...@@ -1798,116 +1789,119 @@ version) requires, and these work on all platforms with a standard C ...@@ -1798,116 +1789,119 @@ version) requires, and these work on all platforms with a standard C
implementation. Note that the 1999 version of the C standard added additional implementation. Note that the 1999 version of the C standard added additional
format codes. format codes.
+-----------+--------------------------------+-------+ +-----------+--------------------------------+------------------------+-------+
| Directive | Meaning | Notes | | Directive | Meaning | Example | Notes |
+===========+================================+=======+ +===========+================================+========================+=======+
| ``%a`` | Locale's abbreviated weekday | | | ``%a`` | Weekday as locale's || Sun, Mon, ..., Sat | \(1) |
| | name. | | | | abbreviated name. | (en_US); | |
+-----------+--------------------------------+-------+ | | || So, Mo, ..., Sa | |
| ``%A`` | Locale's full weekday name. | | | | | (de_DE) | |
+-----------+--------------------------------+-------+ +-----------+--------------------------------+------------------------+-------+
| ``%b`` | Locale's abbreviated month | | | ``%A`` | Weekday as locale's full name. || Sunday, Monday, ..., | \(1) |
| | name. | | | | | Saturday (en_US); | |
+-----------+--------------------------------+-------+ | | || Sonntag, Montag, ..., | |
| ``%B`` | Locale's full month name. | | | | | Samstag (de_DE) | |
+-----------+--------------------------------+-------+ +-----------+--------------------------------+------------------------+-------+
| ``%c`` | Locale's appropriate date and | | | ``%w`` | Weekday as a decimal number, | 0, 1, ..., 6 | |
| | time representation. | | | | where 0 is Sunday and 6 is | | |
+-----------+--------------------------------+-------+ | | Saturday. | | |
| ``%d`` | Day of the month as a decimal | | +-----------+--------------------------------+------------------------+-------+
| | number [01,31]. | | | ``%d`` | Day of the month as a | 01, 02, ..., 31 | |
+-----------+--------------------------------+-------+ | | zero-padded decimal number. | | |
| ``%f`` | Microsecond as a decimal | \(1) | +-----------+--------------------------------+------------------------+-------+
| | number [0,999999], zero-padded | | | ``%b`` | Month as locale's abbreviated || Jan, Feb, ..., Dec | \(1) |
| | on the left | | | | name. | (en_US); | |
+-----------+--------------------------------+-------+ | | || Jan, Feb, ..., Dez | |
| ``%H`` | Hour (24-hour clock) as a | | | | | (de_DE) | |
| | decimal number [00,23]. | | +-----------+--------------------------------+------------------------+-------+
+-----------+--------------------------------+-------+ | ``%B`` | Month as locale's full name. || January, February, | \(1) |
| ``%I`` | Hour (12-hour clock) as a | | | | | ..., December (en_US);| |
| | decimal number [01,12]. | | | | || Januar, Februar, ..., | |
+-----------+--------------------------------+-------+ | | | Dezember (de_DE) | |
| ``%j`` | Day of the year as a decimal | | +-----------+--------------------------------+------------------------+-------+
| | number [001,366]. | | | ``%m`` | Month as a zero-padded | 01, 02, ..., 12 | |
+-----------+--------------------------------+-------+ | | decimal number. | | |
| ``%m`` | Month as a decimal number | | +-----------+--------------------------------+------------------------+-------+
| | [01,12]. | | | ``%y`` | Year without century as a | 00, 01, ..., 99 | |
+-----------+--------------------------------+-------+ | | zero-padded decimal number. | | |
| ``%M`` | Minute as a decimal number | | +-----------+--------------------------------+------------------------+-------+
| | [00,59]. | | | ``%Y`` | Year with century as a decimal | 0001, 0002, ..., 2013, | \(2) |
+-----------+--------------------------------+-------+ | | number. | 2014, ...., 9998, 9999 | |
| ``%p`` | Locale's equivalent of either | \(2) | +-----------+--------------------------------+------------------------+-------+
| | AM or PM. | | | ``%H`` | Hour (24-hour clock) as a | 00, 01, ..., 23 | |
+-----------+--------------------------------+-------+ | | zero-padded decimal number. | | |
| ``%S`` | Second as a decimal number | \(3) | +-----------+--------------------------------+------------------------+-------+
| | [00,59]. | | | ``%I`` | Hour (12-hour clock) as a | 01, 02, ..., 12 | |
+-----------+--------------------------------+-------+ | | zero-padded decimal number. | | |
| ``%U`` | Week number of the year | \(4) | +-----------+--------------------------------+------------------------+-------+
| | (Sunday as the first day of | | | ``%p`` | Locale's equivalent of either || AM, PM (en_US); | \(1), |
| | the week) as a decimal number | | | | AM or PM. || am, pm (de_DE) | \(3) |
| | [00,53]. All days in a new | | +-----------+--------------------------------+------------------------+-------+
| | year preceding the first | | | ``%M`` | Minute as a zero-padded | 00, 01, ..., 59 | |
| | Sunday are considered to be in | | | | decimal number. | | |
| | week 0. | | +-----------+--------------------------------+------------------------+-------+
+-----------+--------------------------------+-------+ | ``%S`` | Second as a zero-padded | 00, 01, ..., 59 | \(4) |
| ``%w`` | Weekday as a decimal number | | | | decimal number. | | |
| | [0(Sunday),6]. | | +-----------+--------------------------------+------------------------+-------+
+-----------+--------------------------------+-------+ | ``%f`` | Microsecond as a decimal | 000000, 000001, ..., | \(5) |
| ``%W`` | Week number of the year | \(4) | | | number, zero-padded on the | 999999 | |
| | (Monday as the first day of | | | | left. | | |
| | the week) as a decimal number | | +-----------+--------------------------------+------------------------+-------+
| | [00,53]. All days in a new | | | ``%z`` | UTC offset in the form +HHMM | (empty), +0000, -0400, | \(6) |
| | year preceding the first | | | | or -HHMM (empty string if the | +1030 | |
| | Monday are considered to be in | | | | the object is naive). | | |
| | week 0. | | +-----------+--------------------------------+------------------------+-------+
+-----------+--------------------------------+-------+ | ``%Z`` | Time zone name (empty string | (empty), UTC, EST, CST | |
| ``%x`` | Locale's appropriate date | | | | if the object is naive). | | |
| | representation. | | +-----------+--------------------------------+------------------------+-------+
+-----------+--------------------------------+-------+ | ``%j`` | Day of the year as a | 001, 002, ..., 366 | |
| ``%X`` | Locale's appropriate time | | | | zero-padded decimal number. | | |
| | representation. | | +-----------+--------------------------------+------------------------+-------+
+-----------+--------------------------------+-------+ | ``%U`` | Week number of the year | 00, 01, ..., 53 | \(7) |
| ``%y`` | Year without century as a | | | | (Sunday as the first day of | | |
| | decimal number [00,99]. | | | | the week) as a zero padded | | |
+-----------+--------------------------------+-------+ | | decimal number. All days in a | | |
| ``%Y`` | Year with century as a decimal | \(5) | | | new year preceding the first | | |
| | number [0001,9999]. | | | | Sunday are considered to be in | | |
+-----------+--------------------------------+-------+ | | week 0. | | |
| ``%z`` | UTC offset in the form +HHMM | \(6) | +-----------+--------------------------------+------------------------+-------+
| | or -HHMM (empty string if the | | | ``%W`` | Week number of the year | 00, 01, ..., 53 | \(7) |
| | the object is naive). | | | | (Monday as the first day of | | |
+-----------+--------------------------------+-------+ | | the week) as a decimal number. | | |
| ``%Z`` | Time zone name (empty string | | | | All days in a new year | | |
| | if the object is naive). | | | | preceding the first Monday | | |
+-----------+--------------------------------+-------+ | | are considered to be in | | |
| ``%%`` | A literal ``'%'`` character. | | | | week 0. | | |
+-----------+--------------------------------+-------+ +-----------+--------------------------------+------------------------+-------+
| ``%c`` | Locale's appropriate date and || Tue Aug 16 21:30:00 | \(1) |
| | time representation. | 1988 (en_US); | |
| | || Di 16 Aug 21:30:00 | |
| | | 1988 (de_DE) | |
+-----------+--------------------------------+------------------------+-------+
| ``%x`` | Locale's appropriate date || 08/16/88 (None); | \(1) |
| | representation. || 08/16/1988 (en_US); | |
| | || 16.08.1988 (de_DE) | |
+-----------+--------------------------------+------------------------+-------+
| ``%X`` | Locale's appropriate time || 21:30:00 (en_US); | \(1) |
| | representation. || 21:30:00 (de_DE) | |
+-----------+--------------------------------+------------------------+-------+
| ``%%`` | A literal ``'%'`` character. | % | |
+-----------+--------------------------------+------------------------+-------+
Notes: Notes:
(1) (1)
When used with the :meth:`strptime` method, the ``%f`` directive Because the format depends on the current locale, care should be taken when
accepts from one to six digits and zero pads on the right. ``%f`` is making assumptions about the output value. Field orderings will vary (for
an extension to the set of format characters in the C standard (but example, "month/day/year" versus "day/month/year"), and the output may
implemented separately in datetime objects, and therefore always contain Unicode characters encoded using the locale's default encoding (for
available). example, if the current locale is ``js_JP``, the default encoding could be
any one of ``eucJP``, ``SJIS``, or ``utf-8``; use :meth:`locale.getlocale`
to determine the current locale's encoding).
(2) (2)
When used with the :meth:`strptime` method, the ``%p`` directive only affects The :meth:`strptime` method can parse years in the full [1, 9999] range, but
the output hour field if the ``%I`` directive is used to parse the hour. years < 1000 must be zero-filled to 4-digit width.
(3)
Unlike :mod:`time` module, :mod:`datetime` module does not support
leap seconds.
(4)
When used with the :meth:`strptime` method, ``%U`` and ``%W`` are only used in
calculations when the day of the week and the year are specified.
(5)
The :meth:`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 .. versionchanged:: 3.2
In previous versions, :meth:`strftime` method was restricted to In previous versions, :meth:`strftime` method was restricted to
...@@ -1917,15 +1911,49 @@ Notes: ...@@ -1917,15 +1911,49 @@ Notes:
In version 3.2, :meth:`strftime` method was restricted to In version 3.2, :meth:`strftime` method was restricted to
years >= 1000. years >= 1000.
(3)
When used with the :meth:`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
leap seconds.
(5)
When used with the :meth:`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
available).
(6) (6)
For example, if :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty
``%z`` is replaced with the string ``'-0330'``. strings.
.. versionchanged:: 3.2 For an aware object:
``%z``
:meth:`utcoffset` is transformed into a 5-character string of the form
+HHMM or -HHMM, where HH is a 2-digit string giving the number of UTC
offset hours, and MM is a 2-digit string giving the number of UTC offset
minutes. For example, if :meth:`utcoffset` returns
``timedelta(hours=-3, minutes=-30)``, ``%z`` is replaced with the string
``'-0330'``.
``%Z``
If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty
string. Otherwise ``%Z`` is replaced by the returned value, which must
be a string.
.. versionchanged:: 3.2
When the ``%z`` directive is provided to the :meth:`strptime` method, an When the ``%z`` directive is provided to the :meth:`strptime` method, an
aware :class:`.datetime` object will be produced. The ``tzinfo`` of the aware :class:`.datetime` object will be produced. The ``tzinfo`` of the
result will be set to a :class:`timezone` instance. result will be set to a :class:`timezone` instance.
(7)
When used with the :meth:`strptime` method, ``%U`` and ``%W`` are only used
in calculations when the day of the week and the year are specified.
.. rubric:: Footnotes .. rubric:: Footnotes
.. [#] If, that is, we ignore the effects of Relativity .. [#] If, that is, we ignore the effects of Relativity
Misc/NEWS
View file @ 8ff2f50b
...@@ -298,6 +298,8 @@ Tests ...@@ -298,6 +298,8 @@ Tests
Documentation Documentation
------------- -------------
- Issue #17701: Improving strftime documentation.
- Issue #18440: Clarify that `hash()` can truncate the value returned from an - Issue #18440: Clarify that `hash()` can truncate the value returned from an
object's custom `__hash__()` method. object's custom `__hash__()` method.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7