16.7. logging.config —记录配置¶

16.7.2.1. 字典模式详细信息¶

传递给 dictConfig() 的字典必须包含以下键：

• version - 设置为表示模式版本的整数值。目前唯一有效的值为1，但具有此密钥允许模式演进，同时仍保留向后兼容性。

所有其他键都是可选的，但如果存在，它们将被解释如下所述。在下面提到的配置dict的所有情况下，将检查特殊 '()' 密钥以查看是否需要定制实例化。如果是，则使用下面 用户定义的对象 中描述的机制来创建实例；否则，上下文用于确定要实例化的内容。

• formatters - 相应的值将是一个dict，其中每个键是一个格式化程序标识符，每个值是一个说明如何配置相应的 Formatter 实例的字典。

  对配置的dict搜索密钥 format 和 datefmt （具有 None 的默认值），并且这些用于构造 Formatter 实例。

• filters - 相应的值将是一个dict，其中每个键是一个过滤器id，每个值是一个说明如何配置相应的Filter实例的dict。

  配置dict搜索密钥 name （默认为空字符串），并且这用于构造 logging.Filter 实例。

• handlers - 相应的值将是一个dict，其中每个键是一个处理程序id，每个值是一个dict，说明如何配置相应的处理程序实例。

  将为配置的dict搜索以下键：

  • class （强制性）。这是处理程序类的完全限定名。

  • level （可选）。处理程序的级别。

  • formatter （可选）。此处理程序的格式化程序的ID。

  • filters （可选）。此处理程序的过滤器的ID的列表。

  所有 other 密钥作为关键字参数传递给处理程序的构造函数。例如，给定代码段：

  handlers:
    console:
      class : logging.StreamHandler
      formatter: brief
      level   : INFO
      filters: [allow_foo]
      stream  : ext://sys.stdout
    file:
      class : logging.handlers.RotatingFileHandler
      formatter: precise
      filename: logconfig.log
      maxBytes: 1024
      backupCount: 3
  

  具有id console 的处理程序被实例化为 logging.StreamHandler，使用 sys.stdout 作为基础流。具有id file 的处理程序被实例化为具有关键字参数 filename='logconfig.log', maxBytes=1024, backupCount=3 的 logging.handlers.RotatingFileHandler。

• loggers - 相应的值将是一个dict，其中每个键是一个记录器名称，每个值是一个说明如何配置相应Logger实例的dict。

  将为配置的dict搜索以下键：

  • level （可选）。记录器的级别。

  • propagate （可选）。记录器的传播设置。

  • filters （可选）。此记录器的过滤器的ID列表。

  • handlers （可选）。此记录器的处理程序的ids列表。

  将根据指定的级别，传播，过滤器和处理程序配置指定的记录器。

• root - 这将是根记录器的配置。配置的处理将与任何记录器相同，除了 propagate 设置将不适用。

• incremental - 配置是否被解释为对现有配置的增量。此值默认为 False，这意味着指定的配置将使用与现有 fileConfig() API所使用的语义相同的语义替换现有配置。

  如果指定的值是 True，则按照 增量配置 部分中所述处理配置。

• disable_existing_loggers - 是否禁用任何现有的记录器。此设置反映 fileConfig() 中同名的参数。如果不存在，则此参数默认为 True。如果 incremental 为 True，则忽略此值。

16.7.2.2. 增量配置¶

很难为增量配置提供完全的灵活性。例如，因为诸如过滤器和格式化器之类的对象是匿名的，所以一旦配置被设置，在扩充配置时就不可能引用这样的匿名对象。

此外，一旦配置被建立，在运行时任意地改变记录器，处理器，过滤器，格式化器的对象图就不是有说服力的情况；可以通过设置级别（以及在记录器的情况下，传播标志）来控制记录器和处理器的冗长性。以安全的方式任意地改变对象图在多线程环境中是有问题的；虽然不是不可能，但是它的好处并不值得它为实现增加的复杂性。

因此，当配置dict的 incremental 密钥存在并且是 True 时，系统将完全忽略任何 formatters 和 filters 条目，并且仅处理 handlers 条目中的 level 设置以及 loggers 和 root 条目中的 level 和 propagate 设置。

在配置中使用值dict会使配置通过线路发送，如pickled dicts到套接字侦听器。因此，长时间运行的应用程序的日志记录冗长度可以随时间改变，而无需停止和重新启动应用程序。

16.7.2.3. 对象连接¶

该模式描述了一组日志对象 - 日志记录器，处理程序，格式化程序，过滤器 - 它们在对象图中彼此连接。因此，模式需要表示对象之间的连接。例如，说，一旦配置，特定的记录器已经附加到它特定的处理程序。为了本讨论的目的，我们可以说记录器表示两者之间的连接的源，而处理器是目的地。当然，在配置的对象中，这由记录器保存对处理程序的引用来表示。在配置dict中，这是通过给每个目标对象一个id来明确地标识它，然后使用源对象的配置中的id来指示在具有该id的源和目标对象之间存在连接。

因此，例如，考虑以下YAML代码段：

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

（注意：这里使用YAML，因为它比字典的等效Python源代码形式更容易阅读）。

记录器的id是记录器名称，其将被编程地用于获得对这些记录器的引用，例如。 foo.bar.baz。格式化器和过滤器的ids可以是任何字符串值（如上面的 brief，precise），并且它们是瞬态的，因为它们只对处理配置字典有意义，并且用于确定对象之间的连接，并且在配置调用完成。

上面的代码段表示，名为 foo.bar.baz 的日志记录器应该连接两个处理程序，由处理程序ids h1 和 h2 描述。 h1 的格式化器由id brief 描述，并且 h2 的格式化器由id precise 描述。

16.7.2.4. 用户定义的对象¶

该模式支持处理程序，过滤器和格式化程序的用户定义对象。 （记录器不需要为不同的实例具有不同的类型，因此在此配置模式中不支持用户定义的记录器类。）

要配置的对象由详细描述其配置的字典描述。在一些地方，日志记录系统将能够从上下文中推断对象如何被实例化，但是当用户定义的对象被实例化时，系统将不知道如何做到这一点。为了为用户定义的对象实例化提供完全的灵活性，用户需要提供一个“factory” - 一个可调用，它用配置字典调用并返回实例化的对象。这通过在特殊键 '()' 下可用的工厂的绝对导入路径来表示。这里有一个具体的例子：

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.customFormatterFactory
      bar: baz
      spam: 99.9
      answer: 42

上述YAML代码段定义了三个格式化程序。第一个，具有ID brief，是具有指定格式字符串的标准 logging.Formatter 实例。第二个，具有id default，具有更长的格式，并且还显式地定义时间格式，并且将导致用这两个格式字符串初始化 logging.Formatter。以Python源代码形式表示，brief 和 default 格式化器具有配置子字典:

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

和:

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

并且因为这些字典不包含特殊键 '()'，所以从上下文推断实例化：结果，创建标准 logging.Formatter 实例。第三个格式化器的配置子字典（ID为 custom）为:

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

并且这包含特殊键 '()'，这意味着需要用户定义的实例化。在这种情况下，将使用指定的工厂调用。如果它是一个实际的可调用，它将被直接使用 - 否则，如果你指定一个字符串（如在示例中），实际的可调用将使用正常的导入机制来定位。可调用项将使用配置子字典中的 剩余 项作为关键字参数进行调用。在上面的例子中，假设id为 custom 的格式化程序将被调用返回:

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

键 '()' 已被用作特殊键，因为它不是有效的关键字参数名，因此不会与调用中使用的关键字参数的名称冲突。 '()' 还用作助记符，相应的值是可调用的。

16.7.2.5. 访问外部对象¶

有时，配置需要引用配置外部的对象，例如 sys.stderr。如果配置dict是使用Python代码构建的，这是直接的，但是当通过文本文件（例如JSON，YAML）提供配置时出现问题。在文本文件中，没有标准方法来区分 sys.stderr 和文字字符串 'sys.stderr'。为了方便这种区分，配置系统在字符串值中查找某些特殊的前缀并对其进行特殊处理。例如，如果文本字符串 'ext://sys.stderr' 作为配置中的值提供，则 ext:// 将被剥离，并且该值的其余部分使用正常的导入机制来处理。

以类似于协议处理的方式来进行对这样的前缀的处理：存在寻找与正则表达式 ^(?P<prefix>[a-z]+)://(?P<suffix>.*)$ 匹配的前缀的通用机制，由此，如果识别出 prefix，则以前缀依赖的方式处理 suffix，并且处理的结果替换字符串值。如果前缀不被识别，则字符串值将保持原样。

16.7.2.6. 访问内部对象¶

除了外部对象，有时还需要引用配置中的对象。这将由配置系统隐含地完成它知道的事情。例如，记录器或处理程序中 level 的字符串值 'DEBUG' 将自动转换为值 logging.DEBUG，handlers，filters 和 formatter 条目将获取对象标识并解析为适当的目标对象。

然而，对于 logging 模块不知道的用户定义对象需要更通用的机制。例如，考虑 logging.handlers.MemoryHandler，它接受一个 target 参数，它是另一个要委托的处理程序。由于系统已经知道这个类，所以在配置中，给定的 target 只需要是相关目标处理程序的对象id，并且系统将从id解析为处理程序。然而，如果用户定义具有 alternate 处理程序的 my.package.MyHandler，则配置系统将不知道 alternate 引用处理程序。为了满足这一点，通用解析系统允许用户指定:

handlers:
  file:
    # configuration of file handler goes here

  custom:
    (): my.package.MyHandler
    alternate: cfg://handlers.file

字符串 'cfg://handlers.file' 将以类似的方式解析为具有 ext:// 前缀的字符串，但是查找配置本身而不是导入命名空间。该机制允许以点或索引访问，类似于 str.format 提供的方式。因此，给出以下代码段:

handlers:
  email:
    class: logging.handlers.SMTPHandler
    mailhost: localhost
    fromaddr: my_app@domain.tld
    toaddrs:
      - support_team@domain.tld
      - dev_team@domain.tld
    subject: Houston, we have a problem.

在配置中，字符串 'cfg://handlers' 将解析为具有密钥 handlers 的dict，字符串 'cfg://handlers.email 将解析为具有 handlers dict中的密钥 email 的dict，等等。字符串 'cfg://handlers.email.toaddrs[1] 将解析为 'dev_team.domain.tld'，字符串 'cfg://handlers.email.toaddrs[0]' 将解析为值 'support_team@domain.tld'。可以使用 'cfg://handlers.email.subject' 或等效地使用 'cfg://handlers.email[subject]' 来访问 subject 值。如果键包含空格或非字母数字字符，则只需要使用后一种形式。如果索引值仅由十进制数字组成，则将使用相应的整数值尝试访问，如果需要，则返回到字符串值。

给定一个字符串 cfg://handlers.myhandler.mykey.123，这将解析为 config_dict['handlers']['myhandler']['mykey']['123']。如果字符串指定为 cfg://handlers.myhandler.mykey[123]，系统将尝试从 config_dict['handlers']['myhandler']['mykey'][123] 中检索值，如果失败，则回退到 config_dict['handlers']['myhandler']['mykey']['123']。

16.7.2.7. 导入分辨率和自定义导入器¶

默认情况下，导入分辨率使用内置的 __import__() 函数进行导入。您可能想用您自己的导入机制替换它：如果是，您可以替换 DictConfigurator 或其超类 BaseConfigurator 类的 importer 属性。但是，由于通过描述符从类访问函数的方式，您需要小心。如果你使用一个Python调用来做你的导入，并且你想要在类级别而不是实例级别定义它，你需要用 staticmethod() 包装它。例如:

from importlib import import_module
from logging.config import BaseConfigurator

BaseConfigurator.importer = staticmethod(import_module)

如果您在配置器 instance 上设置import callable，则不需要使用 staticmethod() 换行。