Objektverbindungen

Das Schema soll eine Menge von Logging-Objekten – Logger, Handler, Formatter, Filter – beschreiben, die in einem Objektgraphen miteinander verbunden sind. Daher muss das Schema Verbindungen zwischen den Objekten darstellen. Angenommen, ein bestimmter Logger hat nach der Konfiguration einen bestimmten Handler angehängt. Für die Zwecke dieser Diskussion können wir sagen, dass der Logger die Quelle und der Handler das Ziel einer Verbindung zwischen beiden darstellt. Natürlich wird dies in den konfigurierten Objekten durch die Tatsache repräsentiert, dass der Logger eine Referenz auf den Handler hält. Im Konfigurations-Dictionary geschieht dies, indem jedem Zielobjekt eine ID gegeben wird, die es eindeutig identifiziert, und dann die ID im Konfigurations-Objekt der Quelle verwendet wird, um anzuzeigen, dass eine Verbindung zwischen der Quelle und dem Zielobjekt mit dieser ID besteht.

Betrachten wir zum Beispiel den folgenden YAML-Snippet:

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]

(Hinweis: YAML wird in diesem Dokument verwendet, da es etwas lesbarer ist als die entsprechende Python-Quellform für das Dictionary.)

Die IDs für Logger sind die Loggernamen, die programmatisch verwendet würden, um eine Referenz auf diese Logger zu erhalten, z.B. foo.bar.baz. Die IDs für Formatter und Filter können beliebige Zeichenwerte sein (wie brief, precise oben) und sind flüchtig, d.h. sie sind nur für die Verarbeitung des Konfigurations-Dictionaries aussagekräftig und werden zur Bestimmung von Verbindungen zwischen Objekten verwendet und nicht irgendwo gespeichert, wenn der Konfigurationsaufruf abgeschlossen ist.

Handler-IDs werden speziell behandelt, siehe Abschnitt Handler-IDs unten.

Der obige Snippet gibt an, dass dem Logger namens foo.bar.baz zwei Handler angehängt werden sollen, die durch die Handler-IDs h1 und h2 beschrieben werden. Der Formatter für h1 ist der durch die ID brief beschriebene und der Formatter für h2 ist der durch die ID precise beschriebene.

Benutzerdefinierte Objekte

Das Schema soll benutzerdefinierte Objekte für Handler, Filter und Formatter unterstützen. (Logger benötigen keine unterschiedlichen Typen für verschiedene Instanzen, daher gibt es keine Unterstützung – in der Konfiguration – für benutzerdefinierte Logger-Klassen.)

Zu konfigurierende Objekte werden typischerweise durch Dictionaries beschrieben, die ihre Konfiguration detailliert darstellen. An einigen Stellen kann das Logging-System aus dem Kontext ableiten, wie ein Objekt instanziiert werden soll, aber wenn ein benutzerdefiniertes Objekt instanziiert werden soll, weiß das System nicht, wie dies geschehen soll. Um vollständige Flexibilität für die Instanziierung benutzerdefinierter Objekte zu bieten, muss der Benutzer eine „Factory“ bereitstellen – ein aufrufbares Objekt, das mit einem Konfigurations-Dictionary aufgerufen wird und das instanziierte Objekt zurückgibt. Dies wird durch einen absoluten Importpfad zur Factory signalisiert, der unter dem speziellen Schlüssel '()' verfügbar gemacht wird. Hier ein konkretes Beispiel:

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

Der obige YAML-Snippet definiert drei Formatter. Der erste, mit der ID brief, ist eine Standard-Instanz von logging.Formatter mit dem angegebenen Formatstring. Der zweite, mit der ID default, hat ein längeres Format und definiert auch das Zeitformat explizit und ergibt eine logging.Formatter-Instanz, die mit diesen beiden Formatstrings initialisiert wird. In Python-Quellform dargestellt, haben die Formatter brief und default Konfigurations-Unter-Dictionaries

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

und

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

jeweils, und da diese Dictionaries nicht den speziellen Schlüssel '()' enthalten, wird die Instanziierung aus dem Kontext abgeleitet: als Ergebnis werden Standard-Instanzen von logging.Formatter erstellt. Das Konfigurations-Unter-Dictionary für den dritten Formatter, mit der ID custom, ist

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

und dieses enthält den speziellen Schlüssel '()', was bedeutet, dass eine benutzerdefinierte Instanziierung gewünscht ist. In diesem Fall wird die angegebene Factory-Funktion verwendet. Wenn es sich um eine tatsächliche aufrufbare Funktion handelt, wird sie direkt verwendet – andernfalls, wenn Sie einen String (wie im Beispiel) angeben, wird die tatsächliche aufrufbare Funktion über normale Importmechanismen gefunden. Die aufrufbare Funktion wird mit den *restlichen* Elementen im Konfigurations-Unter-Dictionary als Schlüsselwortargumente aufgerufen. Im obigen Beispiel wird angenommen, dass der Formatter mit der ID custom durch den Aufruf zurückgegeben wird

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

Der Schlüssel '()' wurde als spezieller Schlüssel verwendet, da er kein gültiger Name für ein Schlüsselwortargument ist und daher nicht mit den Namen der in dem Aufruf verwendeten Schlüsselwortargumente kollidiert. Der '()' dient auch als Merkhilfe, dass der entsprechende Wert eine aufrufbare Funktion ist.

Zugriff auf externe Objekte

Es gibt Fälle, in denen eine Konfiguration auf Objekte außerhalb der Konfiguration verweisen muss, z.B. sys.stderr. Wenn das Konfigurations-Dictionary mit Python-Code erstellt wird, ist dies unkompliziert, aber ein Problem tritt auf, wenn die Konfiguration über eine Textdatei (z.B. JSON, YAML) bereitgestellt wird. In einer Textdatei gibt es keine standardmäßige Möglichkeit, sys.stderr vom literalen String 'sys.stderr' zu unterscheiden. Um diese Unterscheidung zu erleichtern, sucht das Konfigurationssystem nach bestimmten Sonderpräfixen in String-Werten und behandelt diese speziell. Wenn beispielsweise der literale String 'ext://sys.stderr' als Wert in der Konfiguration angegeben wird, wird ext:// entfernt und der Rest des Wertes wird über normale Importmechanismen verarbeitet.

Die Behandlung solcher Präfixe erfolgt analog zur Protokollbehandlung: Es wird einen generischen Mechanismus geben, um nach Präfixen zu suchen, die dem regulären Ausdruck ^(?P<prefix>[a-z]+)://(?P<suffix>.*)$ entsprechen, wobei, wenn das prefix erkannt wird, der suffix auf eine präfixabhängige Weise verarbeitet wird und das Ergebnis der Verarbeitung den String-Wert ersetzt. Wenn das Präfix nicht erkannt wird, bleibt der String-Wert unverändert.

Die Implementierung wird eine Reihe von Standardpräfixen wie ext:// bereitstellen, aber es wird möglich sein, den Mechanismus vollständig zu deaktivieren oder zusätzliche oder andere Präfixe für eine spezielle Behandlung bereitzustellen.

Zugriff auf interne Objekte

Neben externen Objekten gibt es manchmal auch die Notwendigkeit, auf Objekte in der Konfiguration zu verweisen. Dies wird vom Konfigurationssystem implizit für Dinge vorgenommen, die es kennt. Zum Beispiel wird der String-Wert 'DEBUG' für eine level in einem Logger oder Handler automatisch in den Wert logging.DEBUG konvertiert, und die Einträge handlers, filters und formatter nehmen eine Objekt-ID an und werden zum entsprechenden Zielobjekt aufgelöst.

Es muss jedoch ein generischerer Mechanismus für den Fall benutzerdefinierter Objekte bereitgestellt werden, die Logging nicht kennt. Nehmen Sie zum Beispiel die Instanz von logging.handlers.MemoryHandler, die einen target als einen anderen Handler, an den delegiert werden soll, entgegennimmt. Da das System diese Klasse bereits kennt, muss in der Konfiguration der angegebene target nur die Objekt-ID des entsprechenden Zielhandlers sein, und das System wird den Handler anhand der ID auflösen. Wenn jedoch ein Benutzer my.package.MyHandler definiert, der einen alternate Handler hat, wüsste das Konfigurationssystem nicht, dass der alternate auf einen Handler verweist. Um dem Rechnung zu tragen, wird ein generisches Auflösungssystem bereitgestellt, das es dem Benutzer ermöglicht, anzugeben

handlers:
  file:
    # configuration of file handler goes here

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

Der literale String 'cfg://handlers.file' wird analog zu den Strings mit dem ext://-Präfix aufgelöst, jedoch durch Suche im Konfigurations-Dictionary selbst anstatt im Import-Namensraum. Der Mechanismus ermöglicht den Zugriff über Punkte oder Indizes, ähnlich wie bei str.format. Daher würde bei folgendem Snippet

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.

in der Konfiguration der String 'cfg://handlers' zu dem Dictionary mit dem Schlüssel handlers aufgelöst, der String 'cfg://handlers.email zu dem Dictionary mit dem Schlüssel email im Dictionary handlers aufgelöst, und so weiter. Der String 'cfg://handlers.email.toaddrs[1] würde zu 'dev_team.domain.tld' aufgelöst und der String 'cfg://handlers.email.toaddrs[0]' zum Wert 'support_team@domain.tld' aufgelöst. Der subject Wert könnte entweder über 'cfg://handlers.email.subject' oder äquivalent über 'cfg://handlers.email[subject]' abgerufen werden. Die letztere Form muss nur verwendet werden, wenn der Schlüssel Leerzeichen oder nicht-alphanumerische Zeichen enthält. Wenn ein Indexwert nur dezimale Ziffern enthält, wird versucht, über den entsprechenden Ganzzahlwert zuzugreifen, wobei bei Bedarf auf den String-Wert zurückgegriffen wird.

Bei einem String cfg://handlers.myhandler.mykey.123 wird dieser zu config_dict['handlers']['myhandler']['mykey']['123'] aufgelöst. Wenn der String als cfg://handlers.myhandler.mykey[123] angegeben wird, versucht das System, den Wert von config_dict['handlers']['myhandler']['mykey'][123] abzurufen, und greift auf config_dict['handlers']['myhandler']['mykey']['123'] zurück, wenn dies fehlschlägt.

Handler-IDs

Einige spezifische Logging-Konfigurationen erfordern die Verwendung von Handler-Levels, um den gewünschten Effekt zu erzielen. Im Gegensatz zu Loggern, die immer anhand ihrer Namen identifiziert werden können, haben Handler keine persistenten Handles, über die Level über einen inkrementellen Konfigurationsaufruf geändert werden können.

Daher schlägt dieses PEP die Hinzufügung einer optionalen name-Eigenschaft zu Handlern vor. Wenn diese verwendet wird, wird ein Eintrag in einem Dictionary hinzugefügt, das den Namen dem Handler zuordnet. (Der Eintrag wird entfernt, wenn der Handler geschlossen wird.) Wenn ein inkrementeller Konfigurationsaufruf erfolgt, werden Handler in diesem Dictionary gesucht, um das Level des Handlers entsprechend dem Wert in der Konfiguration festzulegen. Siehe Abschnitt Inkrementelle Konfiguration für weitere Details.

Theoretisch könnte eine solche „persistente Namens“-Funktion auch für Filter und Formatter bereitgestellt werden. Es gibt jedoch keinen zwingenden Grund, diese inkrementell konfigurieren zu können. Nach dem Prinzip „Praktikabilität schlägt Reinheit“ erhalten nur Handler diese neue name-Eigenschaft. Die ID eines Handlers in der Konfiguration wird sein name.

Das Handler-Namens-Lookup-Dictionary dient nur Konfigurationszwecken und wird nicht Teil der öffentlichen API des Pakets.