Skip to content

C
cpython
Commit 452dd381 authored by David Wolever's avatar David Wolever
Browse files
Options

Issue #17701: Improving strftime documentation

parents d5991421 c23ca48c
Hide whitespace changes
Inline Side-by-side
Showing with 142 additions and 119 deletions
Doc/library/datetime.rst
View file @ 452dd381
......@@ -551,8 +551,9 @@ 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 section
:ref:`strftime-strptime-behavior`.
.. method:: date.__format__(format)
......@@ -730,7 +731,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 section
:ref:`strftime-strptime-behavior`.
.. versionadded:: 2.5
......@@ -1050,7 +1052,8 @@ 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 section
:ref:`strftime-strptime-behavior`.
.. method:: datetime.__format__(format)
......@@ -1283,7 +1286,8 @@ Instance methods:
.. method:: time.strftime(format)
Return a string representing the time, controlled by an explicit format string.
See section :ref:`strftime-strptime-behavior`.
For a complete list of formatting directives, see section
:ref:`strftime-strptime-behavior`.
.. method:: time.__format__(format)
......@@ -1597,27 +1601,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.
.. versionadded:: 2.6
:class:`.time` and :class:`.datetime` objects support a ``%f`` format code
which expands to the number of microseconds in the object, zero-padded on
the left to six places.
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.
......@@ -1630,99 +1613,115 @@ format codes.
The exact range of years for which :meth:`strftime` works also varies across
platforms. Regardless of platform, years before 1900 cannot be used.
+-----------+--------------------------------+-------+
| 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,61]. | |
+-----------+--------------------------------+-------+
| ``%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 | |
| | number. | |
+-----------+--------------------------------+-------+
| ``%z`` | UTC offset in the form +HHMM | \(5) |
| | 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 | 1970, 1988, 2001, 2013 | |
| | number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%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) | \(2) |
+-----------+--------------------------------+------------------------+-------+
| ``%M`` | Minute as a zero-padded | 00, 01, ..., 59 | |
| | decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%S`` | Second as a zero-padded | 00, 01, ..., 61 | \(3) |
| | decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%f`` | Microsecond as a decimal | 000000, 000001, ..., | \(4) |
| | number, zero-padded on the | 999999 | |
| | left. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%z`` | UTC offset in the form +HHMM | (empty), +0000, -0400, | \(5) |
| | 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 | \(6) |
| | (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 | \(6) |
| | (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
......@@ -1737,12 +1736,35 @@ Notes:
produce them in :func:`strftime` output.
(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.
``%f`` is an extension to the set of format characters in the C standard
(but implemented separately in datetime objects, and therefore always
available). When used with the :meth:`strptime` method, the ``%f``
directive accepts from one to six digits and zero pads on the right.
.. versionadded:: 2.6
(5)
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.
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.
(6)
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 @ 452dd381
......@@ -164,6 +164,7 @@ Tests
Documentation
-------------
- Issue #17701: Improving strftime documentation.
- Issue #17844: Refactor a documentation of Python specific encodings.
Add links to encoders and decoders for binary-to-binary codecs.
......
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