8000 bpo-33400: Clarified documentation to indicate no strict adherence to… · python/cpython@eb5abdc · GitHub
[go: up one dir, main page]
Skip to content
8000

Commit eb5abdc

Browse files
miss-islingtonvsajip
miss-islington
and
vsajip
committed
bpo-33400: Clarified documentation to indicate no strict adherence to ISO 8601. (GH-6703)
(cherry picked from commit c4994dc) Co-authored-by: Vinay Sajip <vinay_sajip@yahoo.co.uk>
1 parent d554699 commit eb5abdc

File tree

4 files changed

+22
-20
lines changed

4 files changed

+22
-20
lines changed

‎Doc/howto/logging.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -296,9 +296,9 @@ which should print something like this:
296296
297297
2010-12-12 11:41:42,612 is when this event was logged.
298298
299-
The default format for date/time display (shown above) is ISO8601. If you need
300-
more control over the formatting of the date/time, provide a *datefmt*
301-
argument to ``basicConfig``, as in this example::
299+
The default format for date/time display (shown above) is like ISO8601 or
300+
RFC 3339. If you need more control over the formatting of the date/time, provide
301+
a *datefmt* argument to ``basicConfig``, as in this example::
302302

303303
import logging
304304
logging.basicConfig(format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %I:%M:%S %p')

‎Doc/library/logging.config.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -783,10 +783,10 @@ Sections which specify formatter configuration are typified by the following.
783783
784784
The ``format`` entry is the overall format string, and the ``datefmt`` entry is
785785
the :func:`strftime`\ -compatible date/time format string. If empty, the
786-
package substitutes ISO8601 format date/times, which is almost equivalent to
787-
specifying the date format string ``'%Y-%m-%d %H:%M:%S'``. The ISO8601 format
788-
also specifies milliseconds, which are appended to the result of using the above
789-
format string, with a comma separator. An example time in ISO8601 format is
786+
package substitutes ISO8601-style format date/times, which is almost equivalent to
787+
specifying the date format string ``'%Y-%m-%d %H:%M:%S'``. This format also
788+
specifies milliseconds, which are appended to the result of using the above
789+
format string, with a comma separator. An example time in this format is
790790
``2003-01-23 00:29:50,411``.
791791

792792
The ``class`` entry is optional. It indicates the name of the formatter's class

‎Doc/library/logging.rst

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -515,8 +515,9 @@ The useful mapping keys in a :class:`LogRecord` are given in the section on
515515
Returns a new instance of the :class:`Formatter` class. The instance is
516516
initialized with a format string for the message as a whole, as well as a
517517
format string for the date/time portion of a message. If no *fmt* is
518-
specified, ``'%(message)s'`` is used. If no *datefmt* is specified, the
519-
ISO8601 date format is used.
518+
specified, ``'%(message)s'`` is used. If no *datefmt* is specified, an
519+
ISO8601-like (or RFC3339-like) date format is used. See the
520+
:meth:`formatTime` documentation for more details.
520521

521522
The *style* parameter can be one of '%', '{' or '$' and determines how
522523
the format string will be merged with its data: using one of %-formatting,
@@ -556,8 +557,8 @@ The useful mapping keys in a :class:`LogRecord` are given in the section on
556557
formatters to provide for any specific requirement, but the basic behavior
557558
is as follows: if *datefmt* (a string) is specified, it is used with
558559
:func:`time.strftime` to format the creation time of the
559-
record. Otherwise, the ISO8601 format is used. The resulting string is
560-
returned.
560+
record. Otherwise, an ISO8601-like (or RDC 3339-like) format is used. The
561+
resulting string is returned.
561562

562563
This function uses a user-configurable function to convert the creation
563564
time to a tuple. By default, :func:`time.localtime` is used; to change
@@ -568,7 +569,7 @@ The useful mapping keys in a :class:`LogRecord` are given i 8000 n the section on
568569
attribute in the ``Formatter`` class.
569570

570571
.. versionchanged:: 3.3
571-
Previously, the default ISO 8601 format was hard-coded as in this
572+
Previously, the default ISO8601-like format was hard-coded as in this
572573
example: ``2010-09-06 22:38:15,292`` where the part before the comma is
573574
handled by a strptime format string (``'%Y-%m-%d %H:%M:%S'``), and the
574575
part after the comma is a millisecond value. Because strptime does not

‎Lib/logging/__init__.py

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -473,7 +473,8 @@ def __init__(self, fmt=None, datefmt=None, style='%'):
473473
474474
Initialize the formatter either with the specified format string, or a
475475
default as described above. Allow for specialized date formatting with
476-
the optional datefmt argument (if omitted, you get the ISO8601 format).
476+
the optional datefmt argument. If datefmt is omitted, you get an
477+
ISO8601-like (or RFC 3339-like) format.
477478
478479
Use a style parameter of '%', '{' or '$' to specify that you want to
479480
use one of %-formatting, :meth:`str.format` (``{}``) formatting or
@@ -501,13 +502,13 @@ def formatTime(self, record, datefmt=None):
501502
in formatters to provide for any specific requirement, but the
502503
basic behaviour is as follows: if datefmt (a string) is specified,
503504
it is used with time.strftime() to format the creation time of the
504-
record. Otherwise, the ISO8601 format is used. The resulting
505-
string is returned. This function uses a user-configurable function
506-
to convert the creation time to a tuple. By default, time.localtime()
507-
is used; to change this for a particular formatter instance, set the
508-
'converter' attribute to a function with the same signature as
509-
time.localtime() or time.gmtime(). To change it for all formatters,
510-
for example if you want all logging times to be shown in GMT,
505+
record. Otherwise, an ISO8601-like (or RFC 3339-like) format is used.
506+
The resulting string is returned. This function uses a user-configurable
507+
function to convert the creation time to a tuple. By default,
508+
time.localtime() is used; to change this for a particular formatter
509+
instance, set the 'converter' attribute to a function with the same
510+
signature as time.localtime() or time.gmtime(). To change it for all
511+
formatters, for example if you want all logging times to be shown in GMT,
511512
set the 'converter' attribute in the Formatter class.
512513
"""
513514
ct = self.converter(record.created)

0 commit comments

Comments
 (0)
0