Dictionary Schema Details¶

The dictionary passed todictConfig() must contain the followingkeys:

• version - to be set to an integer value representing the schemaversion. The only valid value at present is 1, but having this keyallows the schema to evolve while still preserving backwardscompatibility.

All other keys are optional, but if present they will be interpretedas described below. In all cases below where a 'configuring dict' ismentioned, it will be checked for the special'()' key to see if acustom instantiation is required. If so, the mechanism described inUser-defined objects below is used to create an instance;otherwise, the context is used to determine what to instantiate.

• formatters - the corresponding value will be a dict in which eachkey is a formatter id and each value is a dict describing how toconfigure the correspondingFormatter instance.

  The configuring dict is searched for the following optional keyswhich correspond to the arguments passed to create aFormatter object:

  • format

  • datefmt

  • style

  • validate (since version >=3.8)

  • defaults (since version >=3.12)

  An optionalclass key indicates the name of the formatter'sclass (as a dotted module and class name). The instantiationarguments are as forFormatter, thus this key ismost useful for instantiating a customised subclass ofFormatter. For example, the alternative classmight present exception tracebacks in an expanded or condensedformat. If your formatter requires different or extra configurationkeys, you should useUser-defined objects.

• filters - the corresponding value will be a dict in which each keyis a filter id and each value is a dict describing how to configurethe corresponding Filter instance.

  The configuring dict is searched for the keyname (defaulting to theempty string) and this is used to construct alogging.Filterinstance.

• handlers - the corresponding value will be a dict in which eachkey is a handler id and each value is a dict describing how toconfigure the corresponding Handler instance.

  The configuring dict is searched for the following keys:

  • class (mandatory). This is the fully qualified name of thehandler class.

  • level (optional). The level of the handler.

  • formatter (optional). The id of the formatter for thishandler.

  • filters (optional). A list of ids of the filters for thishandler.

    在 3.11 版的變更:filters can take filter instances in addition to ids.

  Allother keys are passed through as keyword arguments to thehandler's constructor. For example, given the snippet:

  handlers:console:class:logging.StreamHandlerformatter:brieflevel:INFOfilters:[allow_foo]stream:ext://sys.stdoutfile:class:logging.handlers.RotatingFileHandlerformatter:precisefilename:logconfig.logmaxBytes:1024backupCount:3

  the handler with idconsole is instantiated as alogging.StreamHandler, usingsys.stdout as the underlyingstream. The handler with idfile is instantiated as alogging.handlers.RotatingFileHandler with the keyword argumentsfilename='logconfig.log',maxBytes=1024,backupCount=3.

• loggers - the corresponding value will be a dict in which each keyis a logger name and each value is a dict describing how toconfigure the corresponding Logger instance.

  The configuring dict is searched for the following keys:

  • level (optional). The level of the logger.

  • propagate (optional). The propagation setting of the logger.

  • filters (optional). A list of ids of the filters for thislogger.

    在 3.11 版的變更:filters can take filter instances in addition to ids.

  • handlers (optional). A list of ids of the handlers for thislogger.

  The specified loggers will be configured according to the level,propagation, filters and handlers specified.

• root - this will be the configuration for the root logger.Processing of the configuration will be as for any logger, exceptthat thepropagate setting will not be applicable.

• incremental - whether the configuration is to be interpreted asincremental to the existing configuration. This value defaults toFalse, which means that the specified configuration replaces theexisting configuration with the same semantics as used by theexistingfileConfig() API.

  If the specified value isTrue, the configuration is processedas described in the section onIncremental Configuration.

• disable_existing_loggers - whether any existing non-root loggers areto be disabled. This setting mirrors the parameter of the same name infileConfig(). If absent, this parameter defaults toTrue.This value is ignored ifincremental isTrue.

Incremental Configuration¶

It is difficult to provide complete flexibility for incrementalconfiguration. For example, because objects such as filtersand formatters are anonymous, once a configuration is set up, it isnot possible to refer to such anonymous objects when augmenting aconfiguration.

Furthermore, there is not a compelling case for arbitrarily alteringthe object graph of loggers, handlers, filters, formatters atrun-time, once a configuration is set up; the verbosity of loggers andhandlers can be controlled just by setting levels (and, in the case ofloggers, propagation flags). Changing the object graph arbitrarily ina safe way is problematic in a multi-threaded environment; while notimpossible, the benefits are not worth the complexity it adds to theimplementation.

Thus, when theincremental key of a configuration dict is presentand isTrue, the system will completely ignore anyformatters andfilters entries, and process only thelevelsettings in thehandlers entries, and thelevel andpropagate settings in theloggers androot entries.

Using a value in the configuration dict lets configurations to be sentover the wire as pickled dicts to a socket listener. Thus, the loggingverbosity of a long-running application can be altered over time withno need to stop and restart the application.

Object connections¶

The schema describes a set of logging objects - loggers,handlers, formatters, filters - which are connected to each other inan object graph. Thus, the schema needs to represent connectionsbetween the objects. For example, say that, once configured, aparticular logger has attached to it a particular handler. For thepurposes of this discussion, we can say that the logger represents thesource, and the handler the destination, of a connection between thetwo. Of course in the configured objects this is represented by thelogger holding a reference to the handler. In the configuration dict,this is done by giving each destination object an id which identifiesit unambiguously, and then using the id in the source object'sconfiguration to indicate that a connection exists between the sourceand the destination object with that id.

So, for example, consider the following YAML snippet:

formatters:brief:# configuration for formatter with id 'brief' goes hereprecise:# configuration for formatter with id 'precise' goes herehandlers:h1:#This is an id# configuration of handler with id 'h1' goes hereformatter:briefh2:#This is another id# configuration of handler with id 'h2' goes hereformatter:preciseloggers:foo.bar.baz:# other configuration for logger 'foo.bar.baz'handlers:[h1,h2]

(Note: YAML used here because it's a little more readable than theequivalent Python source form for the dictionary.)

The ids for loggers are the logger names which would be usedprogrammatically to obtain a reference to those loggers, e.g.foo.bar.baz. The ids for Formatters and Filters can be any stringvalue (such asbrief,precise above) and they are transient,in that they are only meaningful for processing the configurationdictionary and used to determine connections between objects, and arenot persisted anywhere when the configuration call is complete.

The above snippet indicates that logger namedfoo.bar.baz shouldhave two handlers attached to it, which are described by the handleridsh1 andh2. The formatter forh1 is that described by idbrief, and the formatter forh2 is that described by idprecise.

User-defined objects¶

The schema supports user-defined objects for handlers, filters andformatters. (Loggers do not need to have different types fordifferent instances, so there is no support in this configurationschema for user-defined logger classes.)

Objects to be configured are described by dictionarieswhich detail their configuration. In some places, the logging systemwill be able to infer from the context how an object is to beinstantiated, but when a user-defined object is to be instantiated,the system will not know how to do this. In order to provide completeflexibility for user-defined object instantiation, the user needsto provide a 'factory' - a callable which is called with aconfiguration dictionary and which returns the instantiated object.This is signalled by an absolute import path to the factory beingmade available under the special key'()'. Here's a concreteexample:

formatters:brief:format:'%(message)s'default:format:'%(asctime)s%(levelname)-8s%(name)-15s%(message)s'datefmt:'%Y-%m-%d%H:%M:%S'custom:():my.package.customFormatterFactorybar:bazspam:99.9answer:42

The above YAML snippet defines three formatters. The first, with idbrief, is a standardlogging.Formatter instance with thespecified format string. The second, with iddefault, has alonger format and also defines the time format explicitly, and willresult in alogging.Formatter initialized with those two formatstrings. Shown in Python source form, thebrief anddefaultformatters have configuration sub-dictionaries:

{'format':'%(message)s'}

和：

{'format':'%(asctime)s%(levelname)-8s%(name)-15s%(message)s','datefmt':'%Y-%m-%d %H:%M:%S'}

respectively, and as these dictionaries do not contain the special key'()', the instantiation is inferred from the context: as a result,standardlogging.Formatter instances are created. Theconfiguration sub-dictionary for the third formatter, with idcustom, is:

{'()':'my.package.customFormatterFactory','bar':'baz','spam':99.9,'answer':42}

and this contains the special key'()', which means thatuser-defined instantiation is wanted. In this case, the specifiedfactory callable will be used. If it is an actual callable it will beused directly - otherwise, if you specify a string (as in the example)the actual callable will be located using normal import mechanisms.The callable will be called with theremaining items in theconfiguration sub-dictionary as keyword arguments. In the aboveexample, the formatter with idcustom will be assumed to bereturned by the call:

my.package.customFormatterFactory(bar='baz',spam=99.9,answer=42)

The key'()' has been used as the special key because it is not avalid keyword parameter name, and so will not clash with the names ofthe keyword arguments used in the call. The'()' also serves as amnemonic that the corresponding value is a callable.

You can also specify a special key'.' whose value is a dictionary is amapping of attribute names to values. If found, the specified attributes willbe set on the user-defined object before it is returned. Thus, with thefollowing configuration:

{'()':'my.package.customFormatterFactory','bar':'baz','spam':99.9,'answer':42,'.'{'foo':'bar','baz':'bozz'}}

the returned formatter will have attributefoo set to'bar' andattributebaz set to'bozz'.

Handler configuration order¶

Handlers are configured in alphabetical order of their keys, and a configuredhandler replaces the configuration dictionary in (a working copy of) thehandlers dictionary in the schema. If you use a construct such ascfg://handlers.foo, then initiallyhandlers['foo'] points to theconfiguration dictionary for the handler namedfoo, and later (once thathandler has been configured) it points to the configured handler instance.Thus,cfg://handlers.foo could resolve to either a dictionary or a handlerinstance. In general, it is wise to name handlers in a way such that dependenthandlers are configured _after_ any handlers they depend on; that allowssomething likecfg://handlers.foo to be used in configuring a handler thatdepends on handlerfoo. If that dependent handler were namedbar,problems would result, because the configuration ofbar would be attemptedbefore that offoo, andfoo would not yet have been configured.However, if the dependent handler were namedfoobar, it would be configuredafterfoo, with the result thatcfg://handlers.foo would resolve toconfigured handlerfoo, and not its configuration dictionary.

Access to external objects¶

There are times where a configuration needs to refer to objectsexternal to the configuration, for examplesys.stderr. If theconfiguration dict is constructed using Python code, this isstraightforward, but a problem arises when the configuration isprovided via a text file (e.g. JSON, YAML). In a text file, there isno standard way to distinguishsys.stderr from the literal string'sys.stderr'. To facilitate this distinction, the configurationsystem looks for certain special prefixes in string values andtreat them specially. For example, if the literal string'ext://sys.stderr' is provided as a value in the configuration,then theext:// will be stripped off and the remainder of thevalue processed using normal import mechanisms.

The handling of such prefixes is done in a way analogous to protocolhandling: there is a generic mechanism to look for prefixes whichmatch the regular expression^(?P<prefix>[a-z]+)://(?P<suffix>.*)$whereby, if theprefix is recognised, thesuffix is processedin a prefix-dependent manner and the result of the processing replacesthe string value. If the prefix is not recognised, then the stringvalue will be left as-is.

Access to internal objects¶

As well as external objects, there is sometimes also a need to referto objects in the configuration. This will be done implicitly by theconfiguration system for things that it knows about. For example, thestring value'DEBUG' for alevel in a logger or handler willautomatically be converted to the valuelogging.DEBUG, and thehandlers,filters andformatter entries will take anobject id and resolve to the appropriate destination object.

However, a more generic mechanism is needed for user-definedobjects which are not known to thelogging module. Forexample, considerlogging.handlers.MemoryHandler, which takesatarget argument which is another handler to delegate to. Sincethe system already knows about this class, then in the configuration,the giventarget just needs to be the object id of the relevanttarget handler, and the system will resolve to the handler from theid. If, however, a user defines amy.package.MyHandler which hasanalternate handler, the configuration system would not know thatthealternate referred to a handler. To cater for this, a genericresolution system allows the user to specify:

handlers:file:# configuration of file handler goes herecustom:():my.package.MyHandleralternate:cfg://handlers.file

The literal string'cfg://handlers.file' will be resolved in ananalogous way to strings with theext:// prefix, but lookingin the configuration itself rather than the import namespace. Themechanism allows access by dot or by index, in a similar way tothat provided bystr.format. Thus, given the following snippet:

handlers:email:class:logging.handlers.SMTPHandlermailhost:localhostfromaddr:my_app@domain.tldtoaddrs:-support_team@domain.tld-dev_team@domain.tldsubject:Houston, we have a problem.

in the configuration, the string'cfg://handlers' would resolve tothe dict with keyhandlers, the string'cfg://handlers.emailwould resolve to the dict with keyemail in thehandlers dict,and so on. The string'cfg://handlers.email.toaddrs[1] wouldresolve to'dev_team@domain.tld' and the string'cfg://handlers.email.toaddrs[0]' would resolve to the value'support_team@domain.tld'. Thesubject value could be accessedusing either'cfg://handlers.email.subject' or, equivalently,'cfg://handlers.email[subject]'. The latter form only needs to beused if the key contains spaces or non-alphanumeric characters. Please notethat the characters[ and] are not allowed in the keys. If anindex value consists only of decimal digits, access will be attemptedusing the corresponding integer value, falling back to the stringvalue if needed.

Given a stringcfg://handlers.myhandler.mykey.123, this willresolve toconfig_dict['handlers']['myhandler']['mykey']['123'].If the string is specified ascfg://handlers.myhandler.mykey[123],the system will attempt to retrieve the value fromconfig_dict['handlers']['myhandler']['mykey'][123], and fall backtoconfig_dict['handlers']['myhandler']['mykey']['123'] if thatfails.

Import resolution and custom importers¶

Import resolution, by default, uses the builtin__import__() functionto do its importing. You may want to replace this with your own importingmechanism: if so, you can replace theimporter attribute of theDictConfigurator or its superclass, theBaseConfigurator class. However, you need to becareful because of the way functions are accessed from classes viadescriptors. If you are using a Python callable to do your imports, and youwant to define it at class level rather than instance level, you need to wrapit withstaticmethod(). For example:

fromimportlibimportimport_modulefromlogging.configimportBaseConfiguratorBaseConfigurator.importer=staticmethod(import_module)

You don't need to wrap withstaticmethod() if you're setting the importcallable on a configuratorinstance.

Configuring QueueHandler and QueueListener¶

If you want to configure aQueueHandler, noting that thisis normally used in conjunction with aQueueListener, youcan configure both together. After the configuration, theQueueListener instancewill be available as thelistener attribute ofthe created handler, and that in turn will be available to you usinggetHandlerByName() and passing the name you have used for theQueueHandler in your configuration. The dictionary schema for configuring the pairis shown in the example YAML snippet below.

handlers:qhand:class:logging.handlers.QueueHandlerqueue:my.module.queue_factorylistener:my.package.CustomListenerhandlers:-hand_name_1-hand_name_2...

Thequeue andlistener keys are optional.

If thequeue key is present, the corresponding value can be one of the following:

• An object implementing theQueue.put_nowaitandQueue.get public API. For instance, this may bean actual instance ofqueue.Queue or a subclass thereof, or a proxyobtained bymultiprocessing.managers.SyncManager.Queue().

  This is of course only possible if you are constructing or modifyingthe configuration dictionary in code.

• A string that resolves to a callable which, when called with no arguments, returnsthe queue instance to use. That callable could be aqueue.Queue subclassor a function which returns a suitable queue instance,such asmy.module.queue_factory().

• A dict with a'()' key which is constructed in the usual way as discussed inUser-defined objects. The result of this construction should be aqueue.Queue instance.

If thequeue key is absent, a standard unboundedqueue.Queue instance iscreated and used.

If thelistener key is present, the corresponding value can be one of the following:

• A subclass oflogging.handlers.QueueListener. This is of course onlypossible if you are constructing or modifying the configuration dictionary incode.

• A string which resolves to a class which is a subclass ofQueueListener, such as'my.package.CustomListener'.

• A dict with a'()' key which is constructed in the usual way as discussed inUser-defined objects. The result of this construction should be acallable with the same signature as theQueueListener initializer.

If thelistener key is absent,logging.handlers.QueueListener is used.

The values under thehandlers key are the names of other handlers in theconfiguration (not shown in the above snippet) which will be passed to the queuelistener.

Any custom queue handler and listener classes will need to be defined with the sameinitialization signatures asQueueHandler andQueueListener.