bpo-22377: Fixes documentation for %Z in datetime (GH-16507)

This fixes the issue discussed in https://bugs.python.org/issue22377
and fixes it according to the comments made by Paul Ganssle @pganssle

* It clarifies which values are acceptable in the table
* It extends the note with a clearer information on the valid values


https://bugs.python.org/issue22377

Author: karlcow

Doc/library/datetime.rst

@@ -2362,7 +2362,7 @@ requires, and these work on all platforms with a standard C implementation.
 |           | string if the object is        | +063415,               |       |
 |           | naive).                        | -030712.345216         |       |
 +-----------+--------------------------------+------------------------+-------+
-| ``%Z``    | Time zone name (empty string   | (empty), UTC, EST, CST |       |
+| ``%Z``    | Time zone name (empty string   | (empty), UTC, GMT      | \(6)  |
 |           | if the object is naive).       |                        |       |
 +-----------+--------------------------------+------------------------+-------+
 | ``%j``    | Day of the year as a           | 001, 002, ..., 366     | \(9)  |
@@ -2533,9 +2533,18 @@ Notes:
       In addition, providing ``'Z'`` is identical to ``'+00:00'``.
 
    ``%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.
+      In :meth:`strftime`, ``%Z`` is replaced by an empty string if
+      :meth:`tzname` returns ``None``; otherwise ``%Z`` is replaced by the
+      returned value, which must be a string.
+
+      :meth:`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``
+
+      So someone living in Japan may have ``JST``, ``UTC``, and ``GMT`` as
+      valid values, but probably not ``EST``. It will raise ``ValueError`` for
+      invalid values.
 
    .. versionchanged:: 3.2
       When the ``%z`` directive is provided to the :meth:`strptime` method, an

Misc/NEWS.d/next/Documentation/2019-10-01-10-53-46.bpo-22377.5ni-iC.rst

@@ -0,0 +1,2 @@
+Improves documentation of the values that :meth:`datetime.datetime.strptime` accepts for ``%Z``.
+Patch by Karl Dubost.