物件連線

該模式旨在描述一組日誌物件——記錄器、處理程式、格式化程式、過濾器——它們在物件圖中相互連線。因此，該模式需要表示物件之間的連線。例如，假設配置完成後，某個特定記錄器附加了某個特定處理程式。為了討論的目的，我們可以說記錄器代表連線的源，而處理程式代表連線的目的地。當然，在配置的物件中，這由記錄器持有處理程式的引用來表示。在配置字典中，這是透過為每個目標物件提供一個唯一標識它的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 的一部分。