traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

[3.7] bpo-34158: Documentation UTC offset update (GH-8377) (GH-9732) 

* 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 018d353c1c and a fix regarding duplicate words for that part was added at bac2d5ba30.
Relevant format string at https://github.com/python/cpython/pull/2896/filesGH-diff-25e2d173c84057d069b7890450714eddR214.
Relevant test case with 6-digit string for microsecond : https://github.com/python/cpython/pull/2896/filesGH-diff-acc40bec51c7de832de3361db3edae52R309.
Table at https://docs.python.org/3.7/library/datetime.htmlGH-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/filesGH-diff-25e2d173c84057d069b7890450714eddR176
Relevant test case at https://github.com/python/cpython/pull/4699/filesGH-diff-25e2d173c84057d069b7890450714edd

* From Martin Panter: some style improvment;
From @pganssle: using f for fractional part of seconds in all file.
(cherry picked from commit 92878829c3)

Co-authored-by: Christophe Nanteuil <35002064+christopheNan@users.noreply.github.com>
This commit is contained in:
Miss Islington (bot) 2018-10-05 19:44:23 -07:00 committed by Ned Deily
parent 2fcaaaca52
commit 0991b9bb94
1 changed files with 21 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
Doc/library/datetime.rst
View File

@ -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'``.