[Python-checkins] bpo-43047: logging.config formatters documentation update (GH-24358)

[miss-islington]

https://github.com/python/cpython/commit/62437a2fa9ebd2352dc1e15ae310895eef6ff981
commit: 62437a2fa9ebd2352dc1e15ae310895eef6ff981
branch: master
author: Ian Wienand <ian at wienand.org>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2021-01-30T02:37:15-08:00
summary:

bpo-43047: logging.config formatters documentation update (GH-24358)



The documentation for some parts of the logging.config formatters has
fallen behind the code.  For example, the dictionary-schema section
does not list the "class" attribute, however it is discussed in the
file/ini discussion; and neither references the style argument which
has been added.

This modifies the dictionary-schema formatters documentation to list
the keys available and overall makes it clearer these are passed to
create a logging.Formatter object.

The logging.Formatter documentation describes the default values of
format/datefmt and the various formatting options.  Since we have now
more clearly described how the configuration is created via this type
of object, we remove the discussion in this document to avoid
duplication and rely on users reading the referenced logging.Formatter
documenation directly for such details.

Instead of duplicating the discussion for the two config types, the
file/ini section is modified to link back to the dictionary-schema
discussion, making it clear the same arguments are accepted.

Automerge-Triggered-By: GH:vsajip

files:
M Doc/library/logging.config.rst

diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst
index 0b5e2fc2a658d..76ff83c5b0284 100644
--- a/Doc/library/logging.config.rst
+++ b/Doc/library/logging.config.rst
@@ -218,18 +218,29 @@ custom instantiation is required.  If so, the mechanism described in
 :ref:`logging-config-dict-userdef` below is used to create an instance;
 otherwise, the context is used to determine what to instantiate.
 
+.. _logging-config-dictschema-formatters:
+
 * *formatters* - the corresponding value will be a dict in which each
   key is a formatter id and each value is a dict describing how to
   configure the corresponding :class:`~logging.Formatter` instance.
 
-  The configuring dict is searched for keys ``format`` and ``datefmt``
-  (with defaults of ``None``) and these are used to construct a
-  :class:`~logging.Formatter` instance.
+  The configuring dict is searched for the following optional keys
+  which correspond to the arguments passed to create a
+  :class:`~logging.Formatter` object:
+
+   * ``format``
+   * ``datefmt``
+   * ``style``
+   * ``validate`` (since version >=3.8)
 
-  .. versionchanged:: 3.8
-     a ``validate`` key (with default of ``True``) can be added into
-     the ``formatters`` section of the configuring dict, this is to
-     validate the format.
+  An optional ``class`` key indicates the name of the formatter's
+  class (as a dotted module and class name).  The instantiation
+  arguments are as for :class:`~logging.Formatter`, thus this key is
+  most useful for instantiating a customised subclass of
+  :class:`~logging.Formatter`.  For example, the alternative class
+  might present exception tracebacks in an expanded or condensed
+  format.  If your formatter requires different or extra configuration
+  keys, you should use :ref:`logging-config-dict-userdef`.
 
 * *filters* - the corresponding value will be a dict in which each key
   is a filter id and each value is a dict describing how to configure
@@ -791,20 +802,13 @@ Sections which specify formatter configuration are typified by the following.
    [formatter_form01]
    format=F1 %(asctime)s %(levelname)s %(message)s
    datefmt=
+   style='%'
+   validate=True
    class=logging.Formatter
 
-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 something 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
-(as a dotted module and class name.)  This option is useful for instantiating a
-:class:`~logging.Formatter` subclass.  Subclasses of
-:class:`~logging.Formatter` can present exception tracebacks in an expanded or
-condensed format.
+The arguments for the formatter configuration are the same as the keys
+in the dictionary schema :ref:`formatters section
+<logging-config-dictschema-formatters>`.
 
 .. note::