对象连接

该模式旨在描述一组日志对象 - 记录器、处理程序、格式化程序、过滤器 - 这些对象在对象图中相互连接。因此，该模式需要表示对象之间的连接。例如，假设配置后，特定记录器已连接到特定处理程序。为了便于讨论，我们可以说记录器代表源，而处理程序代表两个之间连接的目标。当然，在配置的对象中，这通过记录器保存对处理程序的引用来表示。在配置字典中，这是通过为每个目标对象提供一个唯一标识它的 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），它们是短暂的，因为它们仅在处理配置字典时才有意义，用于确定对象之间的连接，并且在配置调用完成后不会保留在任何地方。

处理程序 ID 的处理方式特殊，请参阅以下关于 处理程序 ID 的部分。

上面的代码段表明，名为 foo.bar.baz 的记录器应附加两个处理程序，它们由处理程序 ID 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。以 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)

键 '()' 已用作特殊键，因为它不是有效的关键字参数名称，因此不会与调用中使用的关键字参数的名称发生冲突。 '()' 也可以用作助记符，表示相应的值是一个可调用对象。

访问外部对象

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

处理此类前缀的方式类似于协议处理：将使用一个通用机制来查找与正则表达式 ^(?P<prefix>[a-z]+)://(?P<suffix>.*)$ 匹配的前缀，如果识别出 prefix，则以依赖于前缀的方式处理 suffix，处理结果将替换字符串值。如果未识别出前缀，则字符串值将保持不变。

实现将提供一组标准前缀，例如 ext://，但可以完全禁用此机制，或者提供其他或不同的前缀用于特殊处理。

访问内部对象

除了外部对象之外，有时还需要引用配置中的对象。这将由配置系统针对其已知的事物隐式执行。例如，字符串值 'DEBUG' 用于记录器或处理程序中的 level 将自动转换为值 logging.DEBUG，而 handlers、filters 和 formatter 条目将采用对象 ID 并解析为相应的目标对象。

但是，对于用户定义的（日志记录系统未知的）对象，需要提供更通用的机制。例如，以 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 的字典，字符串 'cfg://handlers.email' 将解析为 handlers 字典中具有键 email 的字典，依此类推。字符串 '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']。

处理程序 ID

某些特定的日志记录配置需要使用处理程序级别来实现所需的效果。但是，与始终可以通过其名称识别的记录器不同，处理程序没有持久性句柄，因此无法通过增量配置调用来更改级别。

因此，此 PEP 建议向处理程序添加可选的 name 属性。如果使用此属性，它将添加一个字典条目，将名称映射到处理程序。（该条目将在处理程序关闭时被移除。）当进行增量配置调用时，将在该字典中查找处理程序，并根据配置中的值设置处理程序级别。有关更多详细信息，请参阅有关 增量配置 的部分。

理论上，也可以为过滤器和格式化程序提供此类“持久性名称”功能。但是，没有充分的理由说明需要能够增量配置这些项。基于实用性胜过纯度的原则，只有处理程序将获得此新的 name 属性。配置中处理程序的 ID 将变为其 name。

处理程序名称查找字典仅用于配置，不会成为包的公共 API 的一部分。