From c4994dc00d9828a99510f3851da93b0e1c18361d Mon Sep 17 00:00:00 2001 From: Vinay Sajip Date: Fri, 4 May 2018 22:20:54 +0100 Subject: bpo-33400: Clarified documentation to indicate no strict adherence to ISO 8601. (GH-6702) --- Doc/howto/logging.rst | 6 +++--- Doc/library/logging.config.rst | 8 ++++---- Doc/library/logging.rst | 11 ++++++----- Lib/logging/__init__.py | 17 +++++++++-------- 4 files changed, 22 insertions(+), 20 deletions(-) diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst index f8b78b6..e9e5580 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 1f9d7c7..b500761 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 f9eda17..9a54bf9 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 9f2c0f0..46c5906 100644 --- a/Lib/logging/__init__.py +++ b/Lib/logging/__init__.py @@ -466,7 +466,8 @@ class Formatter(object): 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 @@ class Formatter(object): 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) -- cgit v0.12