From b5c4d6064cc2ae7042d2dc7b533d74f6c4176a38 Mon Sep 17 00:00:00 2001 From: Vinay Sajip Date: Fri, 27 Jan 2023 19:01:30 +0000 Subject: [doc] Add a section on logging handler configuration order. (GH-101380) --- Doc/library/logging.config.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst index b4d0da1..2daf242 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 -- cgit v0.12