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
Hide 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:
.. method:: date.strftime(format)
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
section :ref:`strftime-strptime-behavior`.
Format codes referring to hours, minutes or seconds will see 0 values. For a
complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
.. method:: date.__format__(format)
Same as :meth:`.date.strftime`. This makes it possible to specify format
string for a :class:`.date` object when using :meth:`str.format`.
See section :ref:`strftime-strptime-behavior`.
string for a :class:`.date` object when using :meth:`str.format`. For a
complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
Example of counting days to an event::
......@@ -793,7 +795,8 @@ Other constructors, all class methods:
*format*. This is equivalent to ``datetime(*(time.strptime(date_string,
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
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:
.. method:: datetime.strftime(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)
Same as :meth:`.datetime.strftime`. This makes it possible to specify format
string for a :class:`.datetime` object when using :meth:`str.format`.
See section :ref:`strftime-strptime-behavior`.
string for a :class:`.datetime` object when using :meth:`str.format`. For a
complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
Examples of working with datetime objects:
......@@ -1399,15 +1404,17 @@ Instance methods:
.. method:: time.strftime(format)
Return a string representing the time, controlled by an explicit format string.
See section :ref:`strftime-strptime-behavior`.
Return a string representing the time, controlled by an explicit format
string. For a complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
.. method:: time.__format__(format)
Same as :meth:`.time.strftime`. This makes it possible to specify format string
for a :class:`.time` object when using :meth:`str.format`.
See section :ref:`strftime-strptime-behavior`.
for a :class:`.time` object when using :meth:`str.format`. For a
complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
.. method:: time.utcoffset()
......@@ -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
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
calls the platform C library's :func:`strftime` function, and platform
variations are common.
......@@ -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
format codes.
+-----------+--------------------------------+-------+
| Directive | Meaning | Notes |
+===========+================================+=======+
| ``%a`` | Locale's abbreviated weekday | |
| | name. | |
+-----------+--------------------------------+-------+
| ``%A`` | Locale's full weekday name. | |
+-----------+--------------------------------+-------+
| ``%b`` | Locale's abbreviated month | |
| | name. | |
+-----------+--------------------------------+-------+
| ``%B`` | Locale's full month name. | |
+-----------+--------------------------------+-------+
| ``%c`` | Locale's appropriate date and | |
| | time representation. | |
+-----------+--------------------------------+-------+
| ``%d`` | Day of the month as a decimal | |
| | number [01,31]. | |
+-----------+--------------------------------+-------+
| ``%f`` | Microsecond as a decimal | \(1) |
| | number [0,999999], zero-padded | |
| | on the left | |
+-----------+--------------------------------+-------+
| ``%H`` | Hour (24-hour clock) as a | |
| | decimal number [00,23]. | |
+-----------+--------------------------------+-------+
| ``%I`` | Hour (12-hour clock) as a | |
| | decimal number [01,12]. | |
+-----------+--------------------------------+-------+
| ``%j`` | Day of the year as a decimal | |
| | number [001,366]. | |
+-----------+--------------------------------+-------+
| ``%m`` | Month as a decimal number | |
| | [01,12]. | |
+-----------+--------------------------------+-------+
| ``%M`` | Minute as a decimal number | |
| | [00,59]. | |
+-----------+--------------------------------+-------+
| ``%p`` | Locale's equivalent of either | \(2) |
| | AM or PM. | |
+-----------+--------------------------------+-------+
| ``%S`` | Second as a decimal number | \(3) |
| | [00,59]. | |
+-----------+--------------------------------+-------+
| ``%U`` | Week number of the year | \(4) |
| | (Sunday as the first day of | |
| | the week) as a decimal number | |
| | [00,53]. All days in a new | |
| | year preceding the first | |
| | Sunday are considered to be in | |
| | week 0. | |
+-----------+--------------------------------+-------+
| ``%w`` | Weekday as a decimal number | |
| | [0(Sunday),6]. | |
+-----------+--------------------------------+-------+
| ``%W`` | Week number of the year | \(4) |
| | (Monday as the first day of | |
| | the week) as a decimal number | |
| | [00,53]. All days in a new | |
| | year preceding the first | |
| | Monday are considered to be in | |
| | week 0. | |
+-----------+--------------------------------+-------+
| ``%x`` | Locale's appropriate date | |
| | representation. | |
+-----------+--------------------------------+-------+
| ``%X`` | Locale's appropriate time | |
| | representation. | |
+-----------+--------------------------------+-------+
| ``%y`` | Year without century as a | |
| | decimal number [00,99]. | |
+-----------+--------------------------------+-------+
| ``%Y`` | Year with century as a decimal | \(5) |
| | number [0001,9999]. | |
+-----------+--------------------------------+-------+
| ``%z`` | UTC offset in the form +HHMM | \(6) |
| | or -HHMM (empty string if the | |
| | the object is naive). | |
+-----------+--------------------------------+-------+
| ``%Z`` | Time zone name (empty string | |
| | if the object is naive). | |
+-----------+--------------------------------+-------+
| ``%%`` | A literal ``'%'`` character. | |
+-----------+--------------------------------+-------+
+-----------+--------------------------------+------------------------+-------+
| Directive | Meaning | Example | Notes |
+===========+================================+========================+=======+
| ``%a`` | Weekday as locale's || Sun, Mon, ..., Sat | \(1) |
| | abbreviated name. | (en_US); | |
| | || So, Mo, ..., Sa | |
| | | (de_DE) | |
+-----------+--------------------------------+------------------------+-------+
| ``%A`` | Weekday as locale's full name. || Sunday, Monday, ..., | \(1) |
| | | Saturday (en_US); | |
| | || Sonntag, Montag, ..., | |
| | | Samstag (de_DE) | |
+-----------+--------------------------------+------------------------+-------+
| ``%w`` | Weekday as a decimal number, | 0, 1, ..., 6 | |
| | where 0 is Sunday and 6 is | | |
| | Saturday. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%d`` | Day of the month as a | 01, 02, ..., 31 | |
| | zero-padded decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%b`` | Month as locale's abbreviated || Jan, Feb, ..., Dec | \(1) |
| | name. | (en_US); | |
| | || Jan, Feb, ..., Dez | |
| | | (de_DE) | |
+-----------+--------------------------------+------------------------+-------+
| ``%B`` | Month as locale's full name. || January, February, | \(1) |
| | | ..., December (en_US);| |
| | || Januar, Februar, ..., | |
| | | Dezember (de_DE) | |
+-----------+--------------------------------+------------------------+-------+
| ``%m`` | Month as a zero-padded | 01, 02, ..., 12 | |
| | decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%y`` | Year without century as a | 00, 01, ..., 99 | |
| | zero-padded decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%Y`` | Year with century as a decimal | 0001, 0002, ..., 2013, | \(2) |
| | number. | 2014, ...., 9998, 9999 | |
+-----------+--------------------------------+------------------------+-------+
| ``%H`` | Hour (24-hour clock) as a | 00, 01, ..., 23 | |
| | zero-padded decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%I`` | Hour (12-hour clock) as a | 01, 02, ..., 12 | |
| | zero-padded decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%p`` | Locale's equivalent of either || AM, PM (en_US); | \(1), |
| | AM or PM. || am, pm (de_DE) | \(3) |
+-----------+--------------------------------+------------------------+-------+
| ``%M`` | Minute as a zero-padded | 00, 01, ..., 59 | |
| | decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%S`` | Second as a zero-padded | 00, 01, ..., 59 | \(4) |
| | decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%f`` | Microsecond as a decimal | 000000, 000001, ..., | \(5) |
| | number, zero-padded on the | 999999 | |
| | left. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%z`` | UTC offset in the form +HHMM | (empty), +0000, -0400, | \(6) |
| | or -HHMM (empty string if the | +1030 | |
| | the object is naive). | | |
+-----------+--------------------------------+------------------------+-------+
| ``%Z`` | Time zone name (empty string | (empty), UTC, EST, CST | |
| | if the object is naive). | | |
+-----------+--------------------------------+------------------------+-------+
| ``%j`` | Day of the year as a | 001, 002, ..., 366 | |
| | zero-padded decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%U`` | Week number of the year | 00, 01, ..., 53 | \(7) |
| | (Sunday as the first day of | | |
| | the week) as a zero padded | | |
| | decimal number. All days in a | | |
| | new year preceding the first | | |
| | Sunday are considered to be in | | |
| | week 0. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%W`` | Week number of the year | 00, 01, ..., 53 | \(7) |
| | (Monday as the first day of | | |
| | the week) as a decimal number. | | |
| | All days in a new year | | |
| | preceding the first Monday | | |
| | are considered to be in | | |
| | 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:
(1)
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).
Because the format depends on the current locale, care should be taken when
making assumptions about the output value. Field orderings will vary (for
example, "month/day/year" versus "day/month/year"), and the output may
contain Unicode characters encoded using the locale's default encoding (for
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)
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.
(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.
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
In previous versions, :meth:`strftime` method was restricted to
......@@ -1917,14 +1911,48 @@ Notes:
In version 3.2, :meth:`strftime` method was restricted to
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)
For example, if :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``,
``%z`` is replaced with the string ``'-0330'``.
For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty
strings.
.. versionchanged:: 3.2
When the ``%z`` directive is provided to the :meth:`strptime` method, an
aware :class:`.datetime` object will be produced. The ``tzinfo`` of the
result will be set to a :class:`timezone` instance.
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
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
in calculations when the day of the week and the year are specified.
.. rubric:: Footnotes
......
Misc/NEWS
View file @ 8ff2f50b
......@@ -298,6 +298,8 @@ Tests
Documentation
-------------
- Issue #17701: Improving strftime documentation.
- Issue #18440: Clarify that `hash()` can truncate the value returned from an
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