mirror of https://github.com/python/cpython
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
This commit is contained in:
parent
5c5a938573
commit
62437a2fa9
|
@ -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:
|
||||
|
||||
.. 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.
|
||||
* ``format``
|
||||
* ``datefmt``
|
||||
* ``style``
|
||||
* ``validate`` (since version >=3.8)
|
||||
|
||||
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::
|
||||
|
||||
|
|
Loading…
Reference in New Issue