[Python-checkins] bpo-33400: Clarified documentation to indicate no strict adherence to ISO 8601. (GH-6702) (GH-6704)
Vinay Sajip
webhook-mailer at python.org
Mon May 28 08:29:15 EDT 2018
https://github.com/python/cpython/commit/eb8516becc267caeb0ca6f9c41e805d1ba1caaa3
commit: eb8516becc267caeb0ca6f9c41e805d1ba1caaa3
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Vinay Sajip <vinay_sajip at yahoo.co.uk>
date: 2018-05-28T13:29:13+01:00
summary:
bpo-33400: Clarified documentation to indicate no strict adherence to ISO 8601. (GH-6702) (GH-6704)
(cherry picked from commit c4994dc00d9828a99510f3851da93b0e1c18361d)
Co-authored-by: Vinay Sajip <vinay_sajip at yahoo.co.uk>
files:
M Doc/howto/logging.rst
M Doc/library/logging.config.rst
M Doc/library/logging.rst
M Lib/logging/__init__.py
diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst
index f8b78b618569..e9e5580df969 100644
--- a/Doc/howto/logging.rst
+++ b/Doc/howto/logging.rst
@@ -296,9 +296,9 @@ which should print something like this:
2010-12-12 11:41:42,612 is when this event was logged.
-The default format for date/time display (shown above) is ISO8601. If you need
-more control over the formatting of the date/time, provide a *datefmt*
-argument to ``basicConfig``, as in this example::
+The default format for date/time display (shown above) is like ISO8601 or
+RFC 3339. If you need more control over the formatting of the date/time, provide
+a *datefmt* argument to ``basicConfig``, as in this example::
import logging
logging.basicConfig(format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %I:%M:%S %p')
diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst
index 1f9d7c7f220b..b5007610c40f 100644
--- a/Doc/library/logging.config.rst
+++ b/Doc/library/logging.config.rst
@@ -790,10 +790,10 @@ Sections which specify formatter configuration are typified by the following.
The ``format`` entry is the overall format string, and the ``datefmt`` entry is
the :func:`strftime`\ -compatible date/time format string. If empty, the
-package substitutes ISO8601 format date/times, which is almost equivalent to
-specifying the date format string ``'%Y-%m-%d %H:%M:%S'``. The ISO8601 format
-also specifies milliseconds, which are appended to the result of using the above
-format string, with a comma separator. An example time in ISO8601 format is
+package substitutes ISO8601-style format date/times, which is almost equivalent to
+specifying the date format string ``'%Y-%m-%d %H:%M:%S'``. This format also
+specifies milliseconds, which are appended to the result of using the above
+format string, with a comma separator. An example time in this format is
``2003-01-23 00:29:50,411``.
The ``class`` entry is optional. It indicates the name of the formatter's class
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index f9eda173ad0d..9a54bf9325a0 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -515,8 +515,9 @@ The useful mapping keys in a :class:`LogRecord` are given in the section on
Returns a new instance of the :class:`Formatter` class. The instance is
initialized with a format string for the message as a whole, as well as a
format string for the date/time portion of a message. If no *fmt* is
- specified, ``'%(message)s'`` is used. If no *datefmt* is specified, the
- ISO8601 date format is used.
+ specified, ``'%(message)s'`` is used. If no *datefmt* is specified, an
+ ISO8601-like (or RFC3339-like) date format is used. See the
+ :meth:`formatTime` documentation for more details.
The *style* parameter can be one of '%', '{' or '$' and determines how
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
formatters to provide for any specific requirement, but the basic behavior
is as follows: if *datefmt* (a string) is specified, it is used with
:func:`time.strftime` to format the creation time of the
- record. Otherwise, the ISO8601 format is used. The resulting string is
- returned.
+ record. Otherwise, an ISO8601-like (or RDC 3339-like) format is used. The
+ resulting string is returned.
This function uses a user-configurable function to convert the creation
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 in the section on
attribute in the ``Formatter`` class.
.. versionchanged:: 3.3
- Previously, the default ISO 8601 format was hard-coded as in this
+ Previously, the default ISO8601-like format was hard-coded as in this
example: ``2010-09-06 22:38:15,292`` where the part before the comma is
handled by a strptime format string (``'%Y-%m-%d %H:%M:%S'``), and the
part after the comma is a millisecond value. Because strptime does not
diff --git a/Lib/logging/__init__.py b/Lib/logging/__init__.py
index 9f2c0f0c58a3..46c590687c7d 100644
--- a/Lib/logging/__init__.py
+++ b/Lib/logging/__init__.py
@@ -466,7 +466,8 @@ def __init__(self, fmt=None, datefmt=None, style='%'):
Initialize the formatter either with the specified format string, or a
default as described above. Allow for specialized date formatting with
- the optional datefmt argument (if omitted, you get the ISO8601 format).
+ the optional datefmt argument. If datefmt is omitted, you get an
+ ISO8601-like (or RFC 3339-like) format.
Use a style parameter of '%', '{' or '$' to specify that you want to
use one of %-formatting, :meth:`str.format` (``{}``) formatting or
@@ -494,13 +495,13 @@ def formatTime(self, record, datefmt=None):
in formatters to provide for any specific requirement, but the
basic behaviour is as follows: if datefmt (a string) is specified,
it is used with time.strftime() to format the creation time of the
- record. Otherwise, the ISO8601 format is used. The resulting
- string is returned. This function uses a user-configurable function
- to convert the creation time to a tuple. By default, time.localtime()
- is used; to change this for a particular formatter instance, set the
- 'converter' attribute to a function with the same signature as
- time.localtime() or time.gmtime(). To change it for all formatters,
- for example if you want all logging times to be shown in GMT,
+ record. Otherwise, an ISO8601-like (or RFC 3339-like) format is used.
+ The resulting string is returned. This function uses a user-configurable
+ function to convert the creation time to a tuple. By default,
+ time.localtime() is used; to change this for a particular formatter
+ instance, set the 'converter' attribute to a function with the same
+ signature as time.localtime() or time.gmtime(). To change it for all
+ formatters, for example if you want all logging times to be shown in GMT,
set the 'converter' attribute in the Formatter class.
"""
ct = self.converter(record.created)
More information about the Python-checkins
mailing list