From 24b3d02fbc905cef54fca012a131483b5325482f Mon Sep 17 00:00:00 2001 From: Vinay Sajip Date: Mon, 5 Sep 2022 07:47:47 +0100 Subject: [PATCH 1/2] gh-84095: Fill documentation gap regarding user-defined objects. (GH-96574) (cherry picked from commit a9d58feccfd956dc99195af6872b06446738d7db) --- Doc/library/logging.config.rst | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst index a1b8dc755ba6b0..d0af1294df7789 100644 --- a/Doc/library/logging.config.rst +++ b/Doc/library/logging.config.rst @@ -524,6 +524,25 @@ valid keyword parameter name, and so will not clash with the names of the keyword arguments used in the call. The ``'()'`` also serves as a mnemonic that the corresponding value is a callable. +You can also specify a special key ``'.'`` whose value is a dictionary is a +mapping of attribute names to values. If found, the specified attributes will +be set on the user-defined object before it is returned. Thus, with the +following configuration:: + + { + '()' : 'my.package.customFormatterFactory', + 'bar' : 'baz', + 'spam' : 99.9, + 'answer' : 42, + '.' { + 'foo': 'bar', + 'baz': 'bozz' + } + } + +the returned formatter will have attribute ``foo`` set to ``'bar'`` and +attribute ``baz`` set to ``'bozz'``. + .. _logging-config-dict-externalobj: @@ -706,7 +725,7 @@ root logger section is given below. The ``level`` entry can be one of ``DEBUG, INFO, WARNING, ERROR, CRITICAL`` or ``NOTSET``. For the root logger only, ``NOTSET`` means that all messages will be -logged. Level values are :func:`eval`\ uated in the context of the ``logging`` +logged. Level values are :ref:`evaluated ` in the context of the ``logging`` package's namespace. The ``handlers`` entry is a comma-separated list of handler names, which must @@ -753,13 +772,13 @@ handler. If blank, a default formatter (``logging._defaultFormatter``) is used. If a name is specified, it must appear in the ``[formatters]`` section and have a corresponding section in the configuration file. -The ``args`` entry, when :func:`eval`\ uated in the context of the ``logging`` +The ``args`` entry, when :ref:`evaluated ` in the context of the ``logging`` package's namespace, is the list of arguments to the constructor for the handler class. Refer to the constructors for the relevant handlers, or to the examples below, to see how typical entries are constructed. If not provided, it defaults to ``()``. -The optional ``kwargs`` entry, when :func:`eval`\ uated in the context of the +The optional ``kwargs`` entry, when :ref:`evaluated ` in the context of the ``logging`` package's namespace, is the keyword argument dict to the constructor for the handler class. If not provided, it defaults to ``{}``. @@ -823,7 +842,7 @@ Sections which specify formatter configuration are typified by the following. [formatter_form01] format=F1 %(asctime)s %(levelname)s %(message)s datefmt= - style='%' + style=% validate=True class=logging.Formatter From 6a2e357d279c5c8a14d47d067808b84f5aa384c2 Mon Sep 17 00:00:00 2001 From: Vinay Sajip Date: Mon, 5 Sep 2022 08:10:53 +0100 Subject: [PATCH 2/2] Undo error introduced during merge. --- Doc/library/logging.config.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst index d0af1294df7789..88a83538230059 100644 --- a/Doc/library/logging.config.rst +++ b/Doc/library/logging.config.rst @@ -725,7 +725,7 @@ root logger section is given below. The ``level`` entry can be one of ``DEBUG, INFO, WARNING, ERROR, CRITICAL`` or ``NOTSET``. For the root logger only, ``NOTSET`` means that all messages will be -logged. Level values are :ref:`evaluated ` in the context of the ``logging`` +logged. Level values are :func:`eval`\ uated in the context of the ``logging`` package's namespace. The ``handlers`` entry is a comma-separated list of handler names, which must @@ -772,13 +772,13 @@ handler. If blank, a default formatter (``logging._defaultFormatter``) is used. If a name is specified, it must appear in the ``[formatters]`` section and have a corresponding section in the configuration file. -The ``args`` entry, when :ref:`evaluated ` in the context of the ``logging`` +The ``args`` entry, when :func:`eval`\ uated in the context of the ``logging`` package's namespace, is the list of arguments to the constructor for the handler class. Refer to the constructors for the relevant handlers, or to the examples below, to see how typical entries are constructed. If not provided, it defaults to ``()``. -The optional ``kwargs`` entry, when :ref:`evaluated ` in the context of the +The optional ``kwargs`` entry, when :func:`eval`\ uated in the context of the ``logging`` package's namespace, is the keyword argument dict to the constructor for the handler class. If not provided, it defaults to ``{}``.