[Python-checkins] bpo-22377: Fixes documentation for %Z in datetime (GH-16507)
Miss Islington (bot)
webhook-mailer at python.org
Tue Nov 26 11:38:49 EST 2019
https://github.com/python/cpython/commit/bc441ed7c1449f06df37905ee6289aa93b85d4cb
commit: bc441ed7c1449f06df37905ee6289aa93b85d4cb
branch: master
author: Karl Dubost <karl+github at la-grange.net>
committer: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
date: 2019-11-26T08:38:41-08:00
summary:
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
files:
A Misc/NEWS.d/next/Documentation/2019-10-01-10-53-46.bpo-22377.5ni-iC.rst
M Doc/library/datetime.rst
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index b1e1b25691d8f..f9a114eeb0a75 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 0000000000000..d2943f75a8436
--- /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.
More information about the Python-checkins
mailing list