Issue #17701: Improving strftime documentation.

1 files changed, 166 insertions, 138 deletions

diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 9d0af67844..27885f9544 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -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