[Python-checkins] [3.11] [doc] Add a section on logging handler configuration order. (GH-101380) (GH-101382)

Fri Jan 27 14:12:23 EST 2023

https://github.com/python/cpython/commit/88a1e6db0ff7856191a5d63d3d26a896f3ae5885
commit: 88a1e6db0ff7856191a5d63d3d26a896f3ae5885
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: vsajip <vinay_sajip at yahoo.co.uk>
date: 2023年01月27日T19:12:18Z
summary:
[3.11] [doc] Add a section on logging handler configuration order. (GH-101380) (GH-101382)
Co-authored-by: Vinay Sajip <vinay_sajip at yahoo.co.uk>
files:
M Doc/library/logging.config.rst

diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst
index 671f3c89ee83..93e452962218 100644
--- a/Doc/library/logging.config.rst
+++ b/Doc/library/logging.config.rst
@@ -564,6 +564,29 @@ attribute ``baz`` set to ``'bozz'``.
 configuration machinery, but set as attribute values as-is.
 
 
+.. _handler-config-dict-order:
+
+Handler configuration order
+"""""""""""""""""""""""""""
+
+Handlers are configured in alphabetical order of their keys, and a configured
+handler replaces the configuration dictionary in (a working copy of) the
+``handlers`` dictionary in the schema. If you use a construct such as
+``cfg://handlers.foo``, then initially ``handlers['foo']`` points to the
+configuration dictionary for the handler named ``foo``, and later (once that
+handler has been configured) it points to the configured handler instance.
+Thus, ``cfg://handlers.foo`` could resolve to either a dictionary or a handler
+instance. In general, it is wise to name handlers in a way such that dependent
+handlers are configured _after_ any handlers they depend on; that allows
+something like ``cfg://handlers.foo`` to be used in configuring a handler that
+depends on handler ``foo``. If that dependent handler were named ``bar``,
+problems would result, because the configuration of ``bar`` would be attempted
+before that of ``foo``, and ``foo`` would not yet have been configured.
+However, if the dependent handler were named ``foobar``, it would be configured
+after ``foo``, with the result that ``cfg://handlers.foo`` would resolve to
+configured handler ``foo``, and not its configuration dictionary.
+
+
 .. _logging-config-dict-externalobj:
 
 Access to external objects
