bpo-34158: Documentation UTC offset update (GH-8377)

* Documentation of UTC offset update Since changes in the UTC offset that allows sub-minute offsets, the documentation needs update: - "%z" format code documentation update Karthikeyan Singaravelan commented on bugs.python.org: Added as part of 018d353c and a fix regarding duplicate words for that part was added at bac2d5ba. Relevant format string at https://github.com/python/cpython/pull/2896/files#diff-25e2d173c84057d069b7890450714eddR214. Relevant test case with 6-digit string for microsecond : https://github.com/python/cpython/pull/2896/files#diff-acc40bec51c7de832de3361db3edae52R309. Table at https://docs.python.org/3.7/library/datetime.html#strftime-and-strptime-behavior could also be updated with microseconds being optional in the second column %z | UTC offset in the form ±HHMM[SS] (empty string if the object is naive). | (empty), +0000, -0400, +1030 - isoformat documentation update According to me, needs confirmation: Relevant format string at https://github.com/python/cpython/pull/4699/files#diff-25e2d173c84057d069b7890450714eddR176 Relevant test case at https://github.com/python/cpython/pull/4699/files#diff-25e2d173c84057d069b7890450714edd * From Martin Panter: some style improvment; From @pganssle: using f for fractional part of seconds in all file.

bpo-34158: Documentation UTC offset update (GH-8377)
* Documentation of UTC offset update Since changes in the UTC offset that allows sub-minute offsets, the documentation needs update: - "%z" format code documentation update Karthikeyan Singaravelan commented on bugs.python.org: Added as part of 018d353c and a fix regarding duplicate words for that part was added at bac2d5ba. Relevant format string at https://github.com/python/cpython/pull/2896/files#diff-25e2d173c84057d069b7890450714eddR214. Relevant test case with 6-digit string for microsecond : https://github.com/python/cpython/pull/2896/files#diff-acc40bec51c7de832de3361db3edae52R309. Table at https://docs.python.org/3.7/library/datetime.html#strftime-and-strptime-behavior could also be updated with microseconds being optional in the second column %z | UTC offset in the form ±HHMM[SS] (empty string if the object is naive). | (empty), +0000, -0400, +1030 - isoformat documentation update According to me, needs confirmation: Relevant format string at https://github.com/python/cpython/pull/4699/files#diff-25e2d173c84057d069b7890450714eddR176 Relevant test case at https://github.com/python/cpython/pull/4699/files#diff-25e2d173c84057d069b7890450714edd * From Martin Panter: some style improvment; From @pganssle: using f for fractional part of seconds in all file.
92878829 · Christophe Nanteuil · Alexander Belopolsky · 7bb9cd0a · 92878829
Commit 92878829 authored Oct 06, 2018 by Christophe Nanteuil Committed by Alexander Belopolsky Oct 05, 2018
Hide whitespace changes
Inline Side-by-side

Showing with 21 additions and 20 deletions

Doc/library/datetime.rst Doc/library/datetime.rst +21 -20

No files found.
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -841,7 +841,7 @@ Other constructors, all class methods:
  Return a :class:`datetime` corresponding to a *date_string* in one of the
  formats emitted by :meth:`date.isoformat` and :meth:`datetime.isoformat`.
  Specifically, this function supports strings in the format(s)
-  ``YYYY-MM-DD[*HH[:MM[:SS[.mmm[mmm]]]][+HH:MM[:SS[.ffffff]]]]``,
+  ``YYYY-MM-DD[*HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]]``,
  where ``*`` can match any single character.

  .. caution::
@@ -1215,13 +1215,13 @@ Instance methods:
 .. method:: datetime.isoformat(sep='T', timespec='auto')

   Return a string representing the date and time in ISO 8601 format,
-   YYYY-MM-DDTHH:MM:SS.mmmmmm or, if :attr:`microsecond` is 0,
+   YYYY-MM-DDTHH:MM:SS.ffffff or, if :attr:`microsecond` is 0,
   YYYY-MM-DDTHH:MM:SS

-   If :meth:`utcoffset` does not return ``None``, a 6-character string is
-   appended, giving the UTC offset in (signed) hours and minutes:
-   YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM or, if :attr:`microsecond` is 0
-   YYYY-MM-DDTHH:MM:SS+HH:MM
+   If :meth:`utcoffset` does not return ``None``, a string is
+   appended, giving the UTC offset:
+   YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]] or, if :attr:`microsecond`
+   is 0 YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]].

   The optional argument *sep* (default ``'T'``) is a one-character separator,
   placed between the date and time portions of the result.  For example,
@@ -1245,7 +1245,7 @@ Instance methods:
     in HH:MM:SS format.
   - ``'milliseconds'``: Include full time, but truncate fractional second
     part to milliseconds. HH:MM:SS.sss format.
-   - ``'microseconds'``: Include full time in HH:MM:SS.mmmmmm format.
+   - ``'microseconds'``: Include full time in HH:MM:SS.ffffff format.

   .. note::

@@ -1522,7 +1522,7 @@ Other constructor:

  Return a :class:`time` corresponding to a *time_string* in one of the
  formats emitted by :meth:`time.isoformat`. Specifically, this function supports
-  strings in the format(s) ``HH[:MM[:SS[.mmm[mmm]]]][+HH:MM[:SS[.ffffff]]]``.
+  strings in the format(s) ``HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]``.

  .. caution::

@@ -1548,10 +1548,10 @@ Instance methods:

 .. method:: time.isoformat(timespec='auto')

-   Return a string representing the time in ISO 8601 format, HH:MM:SS.mmmmmm or, if
+   Return a string representing the time in ISO 8601 format, HH:MM:SS.ffffff or, if
   :attr:`microsecond` is 0, HH:MM:SS If :meth:`utcoffset` does not return ``None``, a
-   6-character string is appended, giving the UTC offset in (signed) hours and
-   minutes: HH:MM:SS.mmmmmm+HH:MM or, if self.microsecond is 0, HH:MM:SS+HH:MM
+   string is appended, giving the UTC offset: HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]
+   or, if self.microsecond is 0, HH:MM:SS+HH:MM[:SS[.ffffff]].

   The optional argument *timespec* specifies the number of additional
   components of the time to include (the default is ``'auto'``).
@@ -1565,7 +1565,7 @@ Instance methods:
     in HH:MM:SS format.
   - ``'milliseconds'``: Include full time, but truncate fractional second
     part to milliseconds. HH:MM:SS.sss format.
-   - ``'microseconds'``: Include full time in HH:MM:SS.mmmmmm format.
+   - ``'microseconds'``: Include full time in HH:MM:SS.ffffff format.

   .. note::

@@ -2091,9 +2091,10 @@ format codes.
 |           | number, zero-padded on the     | 999999                 |       |
 |           | left.                          |                        |       |
 +-----------+--------------------------------+------------------------+-------+
-| ``%z``    | UTC offset in the form         | (empty), +0000, -0400, | \(6)  |
-|           | ±HHMM[SS] (empty string if the | +1030                  |       |
-|           | object is naive).              |                        |       |
+| ``%z``    | UTC offset in the form         | (empty), +0000,        | \(6)  |
+|           | ±HHMM[SS[.ffffff]] (empty      | -0400, +1030,          |       |
+|           | string if the object is        | +063415,               |       |
+|           | naive).                        | -030712.345216         |       |
 +-----------+--------------------------------+------------------------+-------+
 | ``%Z``    | Time zone name (empty string   | (empty), UTC, EST, CST |       |
 |           | if the object is naive).       |                        |       |
@@ -2206,12 +2207,12 @@ Notes:

   ``%z``
      :meth:`utcoffset` is transformed into a string of the form
-      ±HHMM[SS[.uuuuuu]], 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
+      ±HHMM[SS[.ffffff]], where HH is a 2-digit string giving the number of UTC
+      offset hours, MM is a 2-digit string giving the number of UTC offset
      minutes, SS is a 2-digit string giving the number of UTC offset
-      seconds and uuuuuu is a 2-digit string giving the number of UTC
-      offset microseconds.  The uuuuuu part is omitted when the offset is a
-      whole number of minutes and both the uuuuuu and the SS parts are omitted
+      seconds and ffffff is a 6-digit string giving the number of UTC
+      offset microseconds.  The ffffff part is omitted when the offset is a
+      whole number of seconds and both the ffffff and the SS part is omitted
      when the offset is a whole number of minutes.  For example, if
      :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is
      replaced with the string ``'-0330'``.