From bc441ed7c1449f06df37905ee6289aa93b85d4cb Mon Sep 17 00:00:00 2001 From: Karl Dubost Date: Wed, 27 Nov 2019 01:38:41 +0900 Subject: 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 --- Doc/library/datetime.rst | 17 +++++++++++++---- .../2019-10-01-10-53-46.bpo-22377.5ni-iC.rst | 2 ++ 2 files changed, 15 insertions(+), 4 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2019-10-01-10-53-46.bpo-22377.5ni-iC.rst diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index b1e1b25..f9a114e 100644 --- a/Doc/library/datetime.rst +++ b/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 diff --git a/Misc/NEWS.d/next/Documentation/2019-10-01-10-53-46.bpo-22377.5ni-iC.rst b/Misc/NEWS.d/next/Documentation/2019-10-01-10-53-46.bpo-22377.5ni-iC.rst new file mode 100644 index 0000000..d2943f7 --- /dev/null +++ b/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. -- cgit v0.12