字典架構細節?

傳給 dictConfig() 的字典必須包含以下的鍵:

• version - 應設為代表架構版本的整數值。 目前唯一有效的值是 1，使用此鍵可允許架構在繼續演化的同時(shí)保持向下兼容性。

所有其他鍵都是可選項，但如存在它們將根據下面的描述來(lái)解讀。 在下面提到 'configuring dict' 的所有情況下，都將檢查它的特殊鍵 '()' 以確定是否需要自定義實(shí)例化。 如果需要，則會(huì )使用下面 用戶(hù)定義對象 所描述的機制來(lái)創(chuàng )建一個(gè)實(shí)例；否則，會(huì )使用上下文來(lái)確定要實(shí)例化的對象。

• formatters - 對應的值將是一個(gè)字典，其中每個(gè)鍵是一個(gè)格式器 ID 而每個(gè)值則是一個(gè)描述如何配置相應 Formatter 實(shí)例的字典。

  在配置字典中搜索以下可選鍵，這些鍵對應于創(chuàng )建 Formatter 對象時(shí)傳入的參數。:

  • format

  • datefmt

  • style

  • validate (從版本 >=3.8 起)

  可選的 class 鍵指定格式化器類(lèi)的名稱(chēng)（形式為帶點(diǎn)號的模塊名和類(lèi)名）。 實(shí)例化的參數與 Formatter 的相同，因此這個(gè)鍵對于實(shí)例化自定義的 Formatter 子類(lèi)最為有用。 如果，替代類(lèi)可能 會(huì )以擴展和精簡(jiǎn)格式呈現異?；厮菪畔?。 如果你的格式化器需要不同的或額外的配置鍵，你應當使用 用戶(hù)定義對象。

• filters - 對應的值將是一個(gè)字典，其中每個(gè)鍵是一個(gè)過(guò)濾器 ID 而每個(gè)值則是一個(gè)描述如何配置相應 Filter 實(shí)例的字典。

  將在配置字典中搜索鍵 name (默認值為空字符串) 并且該鍵會(huì )被用于構造 logging.Filter 實(shí)例。

• handlers - 對應的值將是一個(gè)字典，其中每個(gè)鍵是一個(gè)處理器 ID 而每個(gè)值則是一個(gè)描述如何配置相應 Handler 實(shí)例的字典。

  將在配置字典中搜索下列鍵:

  • class (強制)。 這是處理器類(lèi)的完整限定名稱(chēng)。

  • level (可選)。 處理器的級別。

  • formatter (可選)。 處理器所對應格式化器的 ID。

  • filters (可選)。 由處理器所對應過(guò)濾器的 ID 組成的列表。

    在 3.11 版更改: filters can take filter instances in addition to ids.

  所有 其他 鍵會(huì )被作為關(guān)鍵字參數傳遞給處理器類(lèi)的構造器。 例如，給定如下配置:

  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 的處理器會(huì )被實(shí)例化為 logging.StreamHandler，并使用 sys.stdout 作為下層流。 ID 為 file 的處理器會(huì )被實(shí)例化為 logging.handlers.RotatingFileHandler，并附帶關(guān)鍵字參數 filename='logconfig.log', maxBytes=1024, backupCount=3。

• loggers - 對應的值將是一個(gè)字典，其中每個(gè)鍵是一個(gè)日志記錄器名稱(chēng)而每個(gè)值則是一個(gè)描述如何配置相應 Logger 實(shí)例的字典。

  將在配置字典中搜索下列鍵:

  • level (可選)。 日志記錄器的級別。

  • propagate (可選)。 日志記錄器的傳播設置。

  • filters (可選)。 由日志記錄器對應過(guò)濾器的 ID 組成的列表。

    在 3.11 版更改: filters can take filter instances in addition to ids.

  • handlers (可選)。 由日志記錄器對應處理器的 ID 組成的列表。

  指定的記錄器將根據指定的級別、傳播、過(guò)濾器和處理器來(lái)配置。

• root - 這將成為根日志記錄器對應的配置。 配置的處理方式將與所有日志記錄器一致，除了 propagate 設置將不可用之外。

• incremental - 配置是否要被解讀為在現有配置上新增。 該值默認為 False，這意味著(zhù)指定的配置將以與當前 fileConfig() API 所使用的相同語(yǔ)義來(lái)替代現有的配置。

  如果指定的值為 True，配置會(huì )按照 增量配置 部分所描述的方式來(lái)處理。

• disable_existing_loggers - 是否要禁用任何現有的非根日志記錄器。 該設置對應于 fileConfig() 中的同名形參。 如果省略，則此形參默認為 True。 如果 incremental 為 True 則該省會(huì )被忽略。

增量配置?

為增量配置提供完全的靈活性是很困難的。 例如，由于過(guò)濾器和格式化器這樣的對象是匿名的，一旦完成配置，在增加配置時(shí)就不可能引用這些匿名對象。

此外，一旦完成了配置，在運行時(shí)任意改變日志記錄器、處理器、過(guò)濾器、格式化器的對象圖就不是很有必要；日志記錄器和處理器的詳細程度只需通過(guò)設置級別即可實(shí)現控制（對于日志記錄器則可設置傳播旗標）。 在多線(xiàn)程環(huán)境中以安全的方式任意改變對象圖也許會(huì )導致問(wèn)題；雖然并非不可能，但這樣做的好處不足以抵銷(xiāo)其所增加的實(shí)現復雜度。

這樣，當配置字典的 incremental 鍵存在且為 True 時(shí)，系統將完全忽略任何 formatters 和 filters 條目，并僅會(huì )處理 handlers 條目中的 level 設置，以及 loggers 和 root 條目中的 level 和 propagate 設置。

使用配置字典中的值可讓配置以封存字典對象的形式通過(guò)線(xiàn)路傳送給套接字監聽(tīng)器。 這樣，長(cháng)時(shí)間運行的應用程序的日志記錄的詳細程度可隨時(shí)間改變而無(wú)須停止并重新啟動(dòng)應用程序。

對象連接?

該架構描述了一組日志記錄對象 —— 日志記錄器、處理器、格式化器、過(guò)濾器 —— 它們在對象圖中彼此連接。 因此，該架構需要能表示對象之間的連接。 例如，在配置完成后，一個(gè)特定的日志記錄器關(guān)聯(lián)到了一個(gè)特定的處理器。 出于討論的目的，我們可以說(shuō)該日志記錄器代表兩者間連接的源頭，而處理器則代表對應的目標。 當然在已配置對象中這是由包含對處理器的引用的日志記錄器來(lái)代表的。 在配置字典中，這是通過(guò)給每個(gè)目標對象一個(gè) ID 來(lái)無(wú)歧義地標識它，然后在源頭對象中使用該 ID 來(lái)實(shí)現的。

因此，舉例來(lái)說(shuō)，考慮以下 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 是因為它的可讀性比表示字典的等價(jià) Python 源碼形式更好。）

日志記錄器 ID 就是日志記錄器的名稱(chēng)，它會(huì )在程序中被用來(lái)獲取對日志記錄器的引用，例如 foo.bar.baz。 格式化器和過(guò)濾器的 ID 可以是任意字符串值 (例如上面的 brief, precise) 并且它們是瞬態(tài)的，因為它們僅對處理配置字典有意義并會(huì )被用來(lái)確定對象之間的連接，而當配置調用完成時(shí)不會(huì )在任何地方保留。

上面的代碼片段指明名為 foo.bar.baz 的日志記錄器應當關(guān)聯(lián)到兩個(gè)處理器，它們的 ID 是 h1 和 h2。 h1 的格式化器的 ID 是 brief，而 h2 的格式化器的 ID 是 precise。

用戶(hù)定義對象?

此架構支持用戶(hù)定義對象作為處理器、過(guò)濾器和格式化器。 （日志記錄器的不同實(shí)例不需要具有不同類(lèi)型，因此這個(gè)配置架構并不支持用戶(hù)定義日志記錄器類(lèi)。）

要配置的對象是由字典描述的，其中包含它們的配置詳情。 在某些地方，日志記錄系統將能夠從上下文中推斷出如何實(shí)例化一個(gè)對象，但是當要實(shí)例化一個(gè)用戶(hù)自定義對象時(shí)，系統將不知道要如何做。 為了提供用戶(hù)自定義對象實(shí)例化的完全靈活性，用戶(hù)需要提供一個(gè)‘工廠(chǎng)’函數 —— 即在調用時(shí)傳入配置字典并返回實(shí)例化對象的可調用對象。 這是用一個(gè)通過(guò)特殊鍵 '()' 來(lái)訪(fǎng)問(wèn)的工廠(chǎng)函數的絕對導入路徑來(lái)標示的。 下面是一個(gè)實(shí)際的例子:

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 代碼片段定義了三個(gè)格式化器。 第一個(gè)的 ID 為 brief，是帶有特殊格式字符串的標準 logging.Formatter 實(shí)例。 第二個(gè)的 ID 為 default，具有更長(cháng)的格式同時(shí)還顯式地定義了時(shí)間格式，并將最終實(shí)例化一個(gè)帶有這兩個(gè)格式字符串的 logging.Formatter。 以 Python 源代碼形式顯示的 brief 和 default 格式化器分別具有下列配置子字典:

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

和:

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

并且由于這些字典不包含特殊鍵 '()'，實(shí)例化方式是從上下文中推斷出來(lái)的：結果會(huì )創(chuàng )建標準的 logging.Formatter 實(shí)例。 第三個(gè)格式器的 ID 為 custom，對應配置子字典為:

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

并且它包含特殊鍵 '()'，這意味著(zhù)需要用戶(hù)自定義實(shí)例化方式。 在此情況下，將使用指定的工廠(chǎng)可調用對象。 如果它本身就是一個(gè)可調用對象則將被直接使用 —— 否則如果你指定了一個(gè)字符串（如這個(gè)例子所示）則將使用正常的導入機制來(lái)定位實(shí)例的可調用對象。 調用該可調用對象將傳入配置子字典中 剩余的 條目作為關(guān)鍵字參數。 在上面的例子中，調用將預期返回 ID 為 custom 的格式化器:

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

將 '()' 用作特殊鍵是因為它不是一個(gè)有效的關(guān)鍵字形參名稱(chēng)，這樣就不會(huì )與調用中使用的關(guān)鍵字參數發(fā)生沖突。 '()' 還被用作表明對應值為可調用對象的助記符。

在 3.11 版更改: The filters member of handlers and loggers can take filter instances in addition to ids.

訪(fǎng)問(wèn)外部對象?

有時(shí)一個(gè)配置需要引用配置以外的對象，例如 sys.stderr。 如果配置字典是使用 Python 代碼構造的，這會(huì )很直觀(guān)，但是當配置是通過(guò)文本文件（例如 JSON, YAML）提供的時(shí)候就會(huì )引發(fā)問(wèn)題。 在一個(gè)文本文件中，沒(méi)有將 sys.stderr 與字符串字面值 'sys.stderr' 區分開(kāi)來(lái)的標準方式。 為了實(shí)現這種區分，配置系統會(huì )在字符串值中查找規定的特殊前綴并對其做特殊處理。 例如，如果在配置中將字符串字面值 'ext://sys.stderr' 作為一個(gè)值來(lái)提供，則 ext:// 將被去除而該值的剩余部分將使用正常導入機制來(lái)處理。

此類(lèi)前綴的處理方式類(lèi)似于協(xié)議處理：存在一種通用機制來(lái)查找與正則表達式 ^(?P<prefix>[a-z]+)://(?P<suffix>.*)$ 相匹配的前綴，如果識別出了 prefix，則 suffix 會(huì )以與前綴相對應的方式來(lái)處理并且處理的結果將替代原字符串值。 如果未識別出前綴，則原字符串將保持不變。

訪(fǎng)問(wèn)內部對象?

除了外部對象，有時(shí)還需要引用配置中的對象。 這將由配置系統針對它所了解的內容隱式地完成。 例如，在日志記錄器或處理器中表示 level 的字符串值 'DEBUG' 將被自動(dòng)轉換為值 logging.DEBUG，而 handlers, filters 和 formatter 條目將接受一個(gè)對象 ID 并解析為適當的目標對象。

但是，對于 logging 模塊所不了解的用戶(hù)自定義對象則需要一種更通用的機制。 例如，考慮 logging.handlers.MemoryHandler，它接受一個(gè) target 參數即其所委托的另一個(gè)處理器。 由于系統已經(jīng)知道存在該類(lèi)，因而在配置中，給定的 target 只需為相應目標處理器的的對象 ID 即可，而系統將根據該 ID 解析出處理器。 但是，如果用戶(hù)定義了一個(gè)具有 alternate 處理器的 my.package.MyHandler，則配置程序將不知道 alternate 指向的是一個(gè)處理器。 為了應對這種情況，通用解析系統允許用戶(hù)指定:

handlers:
  file:
    # configuration of file handler goes here

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

字符串字面值 'cfg://handlers.file' 將按照與 ext:// 前綴類(lèi)似的方式被解析為結果字符串，但查找操作是在配置自身而不是在導入命名空間中進(jìn)行。 該機制允許按點(diǎn)號或按索引來(lái)訪(fǎng)問(wèn)，與 str.format 所提供的方式類(lèi)似。 這樣，給定以下代碼段:

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 將解析為具有 email 鍵的 handlers 字典中的字典，依此類(lèi)推。 字符串 'cfg://handlers.email.toaddrs[1] 將解析為 'dev_team@domain.tld' 而字符串 'cfg://handlers.email.toaddrs[0]' 將解析為值 'support_team@domain.tld'。 subject 值 可以使用 'cfg://handlers.email.subject' 或者等價(jià)的 'cfg://handlers.email[subject]' 來(lái)訪(fǎng)問(wèn)。 后一種形式僅在鍵包含空格或非字母類(lèi)數字類(lèi)字符的情況下才需要使用。 如果一個(gè)索引僅由十進(jìn)制數碼構成，則將嘗試使用相應的整數值來(lái)訪(fǎng)問(wèn)，如果有必要則將回退為字符串值。

給定字符串 cfg://handlers.myhandler.mykey.123，這將解析為 config_dict['handlers']['myhandler']['mykey']['123']。 如果字符串被指定為 cfg://handlers.myhandler.mykey[123]，系統將嘗試從 config_dict['handlers']['myhandler']['mykey'][123] 中提取值，并在嘗試失敗時(shí)回退為 config_dict['handlers']['myhandler']['mykey']['123']。

導入解析與定制導入器?

導入解析默認使用內置的 __import__() 函數來(lái)執行導入。 你可能想要將其替換為你自己的導入機制：如果是這樣的話(huà)，你可以替換 DictConfigurator 或其超類(lèi) BaseConfigurator 類(lèi)的 importer 屬性。 但是你必須小心謹慎，因為函數是從類(lèi)中通過(guò)描述器方式來(lái)訪(fǎng)問(wèn)的。 如果你使用 Python 可調用對象來(lái)執行導入，并且你希望在類(lèi)層級而不是在實(shí)例層級上定義它，則你需要用 staticmethod() 來(lái)裝飾它。 例如:

from importlib import import_module
from logging.config import BaseConfigurator

BaseConfigurator.importer = staticmethod(import_module)

如果你是在一個(gè)配置器的 實(shí)例 上設置導入可調用對象則你不需要用 staticmethod() 來(lái)裝飾。