Skip to content

bpo-34158: Documentation UTC offset update #8377

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
abalkin merged 2 commits into from
Oct 5, 2018
Merged

bpo-34158: Documentation UTC offset update #8377

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a9631c1
Documentation of UTC offset update
christopheNan Jul 21, 2018
673439a
From Martin Panter: some style improvment;
christopheNan Jul 23, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 21 additions & 20 deletions Doc/library/datetime.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -842,7 +842,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::
Expand Down Expand Up @@ -1216,13 +1216,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]].
Comment thread
abalkin marked this conversation as resolved.

The optional argument *sep* (default ``'T'``) is a one-character separator,
placed between the date and time portions of the result. For example,
Expand All @@ -1246,7 +1246,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::

Expand Down Expand Up @@ -1523,7 +1523,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::

Expand All @@ -1549,10 +1549,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'``).
Expand All @@ -1566,7 +1566,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::

Expand Down Expand Up @@ -2092,9 +2092,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). | | |
Expand Down Expand Up @@ -2207,12 +2208,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'``.
Expand Down