对象连接

该模式旨在描述一组日志对象——记录器、处理程序、格式化程序、过滤器——它们在对象图中相互连接。因此，该模式需要表示对象之间的连接。例如，假设配置完成后，某个特定记录器附加了某个特定处理程序。为了讨论的目的，我们可以说记录器代表连接的源，而处理程序代表连接的目的地。当然，在配置的对象中，这由记录器持有处理程序的引用来表示。在配置字典中，这是通过为每个目标对象提供一个唯一标识它的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源代码形式的字典更具可读性。）

记录器（logger）的ID是用于通过编程方式获取这些记录器引用的记录器名称，例如 foo.bar.baz。格式化程序（Formatter）和过滤器（Filter）的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://，但可以完全禁用该机制，或为特殊处理提供额外或不同的前缀。

访问内部对象

除了外部对象，有时还需要引用配置中的对象。配置系统将隐式地为它知道的事物完成此操作。例如，记录器或处理程序中 level 的字符串值 'DEBUG' 将自动转换为值 logging.DEBUG，并且 handlers、filters 和 formatter 条目将接受一个对象ID并解析为相应的目标对象。

然而，对于日志系统未知的用户定义对象，需要提供一个更通用的机制。例如，以 logging.handlers.MemoryHandler 实例为例，它接受一个 target，该 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'。subject 值可以通过 'cfg://handlers.email.subject' 或等效地 'cfg://handlers.email[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 的一部分。