diff options
| author | Karl Dubost <karl+github@la-grange.net> | 2019-11-26 16:38:41 (GMT) |
|---|---|---|
| committer | Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> | 2019-11-26 16:38:41 (GMT) |
| commit | bc441ed7c1449f06df37905ee6289aa93b85d4cb (patch) | |
| tree | 6a1cf146367706034384d4d82d0a24b5087effeb | |
| parent | 036fe85bd3e6cd01093d836d71792a1966f961e8 (diff) | |
| download | cpython-bc441ed7c1449f06df37905ee6289aa93b85d4cb.zip cpython-bc441ed7c1449f06df37905ee6289aa93b85d4cb.tar.gz cpython-bc441ed7c1449f06df37905ee6289aa93b85d4cb.tar.bz2 | |
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
| -rw-r--r-- | Doc/library/datetime.rst | 17 | ||||
| -rw-r--r-- | Misc/NEWS.d/next/Documentation/2019-10-01-10-53-46.bpo-22377.5ni-iC.rst | 2 |
2 files changed, 15 insertions, 4 deletions
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. |