Dictionary Schema Details

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

• version – 设置为表示schemaversion的整数值。目前唯一有效的值是1，但是这样可以保持模式的发展，同时仍然保持向后兼容性.

所有其他键都是可选的，但如果存在，它们将被解释如下所述。在下面提到“配置字典”的所有情况下，将检查特殊的"()"键以查看是否需要自定义实例化。如果是这样，中描述的用户定义对象中描述的机制用于创建实例;否则，上下文用于确定要实例化的内容.

• formatters -相应的值将是一个dict，其中每个键是一个格式化程序ID，每个值都是一个描述如何配置相应的Formatter实例的字典

  搜索配置字典的密钥format和datefmt（默认值为None）这些用于构造Formatter instance.

• filters – 相应的值将是一个dict in其中每个键都是一个过滤器ID，每个值都是一个描述如何配置相应过滤器实例的字典.

  在配置字典中搜索密钥name（默认为空字符串）这用于构造logging.Filterinstance.

• handlers – 相应的值将是一个dict，其中每个键是一个处理程序ID，每个值是一个描述如何的字典配置相应的Handler实例.

  在配置字典中搜索以下键：

  • class（强制）。这是处理程序类的完全限定名称.
  • level（可选）。handler.
  • formatter（可选）的级别。thishandler的格式化程序的id
  • filters//（可选）。thishandler的过滤器的id列表

  所有other键作为关键字参数传递给handler的构造函数。例如，给定片段：

  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的处理程序用关键字arguments logging.handlers.RotatingFileHandler实例化为filename="logconfig.log", maxBytes=1024, backupCount=3.

• loggers– 相应的值将是一个dict，其中每个键是一个记录器名称，每个值都是一个描述如何配置相应的Logger实例的字典.

  在配置字典中搜索以下键：

  • level （可选的）。记录器的级别.
  • propagate（可选）。记录器的传播设置.
  • filters（可选）。thislogger.
  • handlers（可选）的过滤器ID列表。thislogger的处理程序ID列表

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

• root – 这将是根记录器的配置。配置的处理将与任何记录器一样，但propagate设置将不适用.

• incremental – 配置是否被解释为对现有配置的增量。此值默认为False，这意味着指定的配置将使用与现有fileConfig()API.

  如果指定的值为True，则按增量配置.

• disable_existing_loggers一节中的描述处理配置 – 是否存在任何非root用户记录器被禁用。此设置镜像fileConfig()中相同名称的参数。如果不存在，则此参数默认为True。如果incremental是True.

，则忽略此值。增量配置

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

此外，一旦配置完成，就没有令人信服的案例来随意改变记录器，处理程序，过滤器，格式化程序的对象图。记录器和处理程序的详细程度可以通过设置级别来控制（在记录器的情况下，传播标志）。在多线程环境中以安全的方式任意改变对象图是有问题的;虽然不可能，但实际上增加的复杂性并不值得实现.

因此，当配置字典的incremental键存在且是True时，系统将完全忽略任何formatters和filters条目，只处理level条目中的handlers设置，以及level和propagate loggers和root条目中的设置

使用配置dict中的值可以将配置作为pickled dicts发送到线程侦听器。因此，长时间运行的应用程序的loggingverbosity可以随着时间的推移而改变，无需停止和重新启动应用程序.

对象连接

该模式描述了一组日志对象 – 记录器，处理程序，格式化程序，过滤器 – 它们在对象图中相互连接。因此，模式需要表示对象之间的连接。例如，假设一旦配置，特定记录器就会附加一个特定的处理程序。对于本讨论的目的，我们可以说记录器代表两者之间连接的源和目标处理程序。当然，在配置的对象中，这由持有对处理程序的引用的记录器表示。在配置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。格式化程序和过滤器的ID可以是任何字符串值（例如brief, precise以上），它们是瞬态的，因为它们仅对处理配置字典有意义并用于确定对象之间的连接，并且不会在任何地方持久存在配置调用完成.

上面的代码片段表示名为foo.bar.baz的记录器应该附加两个处理程序，由处理程序h1和h2描述。h1的格式化程序是由id brief描述的，h2的格式化程序是由id precise.

描述的用户定义的对象

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

要配置的对象由字典描述，详细说明了它们的配置。在某些地方，日志记录系统将能够从上下文推断出如何实例化对象，但是当要实例化用户定义的对象时，系统将不知道如何执行此操作。为了为用户定义的对象实例化提供完全灵活性，用户需要提供一个’工厂’ – 一个可调用的，使用配置字典调用并返回实例化的对象。这是通过工厂提供的绝对导入路径来表示的。特殊键"()"。这是一个具体的例子：

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中用这两个格式字符串初始化。以//源代码形式显示，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
}

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

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

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

访问外部对象

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

这种前缀的处理方式是以类似于协议处理的方式完成的：有一种通用机制来查找与正则表达式匹配的前缀^(?P<prefix>[a-z]+)://(?P<suffix>.*)$，其中，如果prefix是公认的，suffix以前缀相关的方式处理，处理结果替换字符串值。如果无法识别前缀，则字符串值将保留为–is.

访问内部对象

除了外部对象之外，有时还需要在配置中引用对象。这将由配置系统隐式地完成它所知道的事情。例如，字符串值"DEBUG"为一个 level在记录器或处理程序中，willautomatically将转换为值logging.DEBUG，并且handlers, filters和formatter条目将采用对象ID并解析为适当的目标对象.

但是，对于logging模块不知道的用户定义对象，需要更通用的机制。例如，考虑logging.handlers.MemoryHandler，这需要target参数，这是另一个委托给它的处理程序。由于系统已经知道了这个类，所以在配置中，给定的target只需要是相关目标处理程序的对象id，系统将从theid解析为处理程序。但是，如果用户定义my.package.MyHandler其中有alternate处理程序，配置系统将不知道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: [email protected]
    toaddrs:
      - [email protected]
      - [email protected]
    subject: Houston, we have a problem.

在配置中，字符串"cfg://handlers"将使用键handlers解析为dict，字符串"cfg://handlers.email将解析为在email dict中用键handlers敲词，依此类推。字符串"cfg://handlers.email.toaddrs[1]将解析为"dev_team.domain.tld"并且字符串"cfg://handlers.email.toaddrs[0]"将解析为值"[email protected]"。使用subject或等同于"cfg://handlers.email.subject"可以访问"cfg://handlers.email[subject]"值。如果密钥包含空格或非字母数字字符，则只需要使用后一种形式。如果anindex值只包含十进制数字，则会尝试使用相应的整数值进行访问，如果需要则返回stringvalue .

给一个字符串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"]iffails.

导入解析和自定义导入程序

默认情况下，导入解析使用内置的__import__()函数进行导入。您可能希望用您自己的importmechanism替换它：如果是这样，您可以替换importer或其超类DictConfigurator类的BaseConfigurator属性。但是，由于从类viadescriptors访问函数的方式，您需要考虑因素。如果您使用Python可调用来执行导入，并且您希望在类级别而不是实例级别定义它，则需要使用staticmethod()进行换行。例如：

from importlib import import_module
from logging.config import BaseConfigurator

BaseConfigurator.importer = staticmethod(import_module)

如果在配置程序中设置importcallable，则不需要用staticmethod()包装instance.