Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 102 additions & 0 deletions docs/setups.rst
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,108 @@ it was a single handler:
...


.. _configuration-from-dictionaries:

Configuration from Dictionaries and Files
-----------------------------------------

:meth:`NestedSetup.from_dict <logbook.NestedSetup.from_dict>` creates a setup
from a mapping. The ``objects`` list follows the same order as the objects
passed to :class:`~logbook.NestedSetup`: handlers later in the list see a
record first. Each entry contains a fully qualified ``class`` name and
keyword arguments for that class::

from logbook import NestedSetup

config = {
"objects": [
{"class": "logbook.NullHandler"},
{"class": "logbook.StderrHandler", "level": "WARNING"},
]
}
setup = NestedSetup.from_dict(config)
with setup.applicationbound():
main()

This setup writes warnings and errors to standard error and discards lower
levels. Construction does not activate the setup. Use ``with setup`` for the
current context, or ``setup.applicationbound()`` for the whole application.
As with a manually constructed nested setup, popping it does not close its
handlers; close handlers that own resources when you are finished using them.

The mapping may be loaded from a file using a parser of your choice. For
example, a JSON file named ``logging.json`` can contain:

.. code-block:: json

{
"objects": [
{"class": "logbook.NullHandler"},
{"class": "logbook.StderrHandler", "level": "WARNING"}
]
}

Load it with the standard library::

import json
from logbook import NestedSetup

with open("logging.json", encoding="utf-8") as stream:
setup = NestedSetup.from_dict(json.load(stream))

The equivalent YAML file is:

.. code-block:: yaml

objects:
- class: logbook.NullHandler
- class: logbook.StderrHandler
level: WARNING

If your application uses PyYAML, load it with ``yaml.safe_load``::

import yaml
from logbook import NestedSetup

with open("logging.yaml", encoding="utf-8") as stream:
setup = NestedSetup.from_dict(yaml.safe_load(stream))

Logbook does not require a YAML parser. In both examples, activate ``setup``
as shown above. Only use trusted configuration files: class names cause
Python modules to be imported and the classes to be instantiated.

Classes must derive from :class:`~logbook.base.ContextObject`, which includes
handlers, processors, and flags. Python dictionaries can also supply class
objects and values such as callbacks directly::

from logbook import NestedSetup, Processor, StderrHandler


def inject_environment(record):
record.extra["environment"] = "production"


setup = NestedSetup.from_dict(
{
"objects": [
{
"class": StderrHandler,
"format_string": "{record.extra[environment]}: {record.message}",
},
{"class": Processor, "callback": inject_environment},
]
}
)

Keyword argument values are passed unchanged. Strings in those values are
not imported, and nested mappings are not interpreted as object definitions.
For callbacks or wrapped handlers, supply the Python objects after loading
the file, or use a custom handler class with suitable constructor arguments.
The input mapping is not modified. Invalid configuration raises an exception;
if construction fails, already created handlers are closed before the
exception is propagated.


Distributed Logging
-------------------

Expand Down
1 change: 1 addition & 0 deletions newsfragments/248.added.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Add :meth:`logbook.NestedSetup.from_dict` to build logging setups from mappings, including configurations loaded from JSON or YAML files.
70 changes: 70 additions & 0 deletions src/logbook/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,10 @@
import traceback
import warnings
from collections import defaultdict
from collections.abc import Mapping
from contextlib import suppress
from datetime import datetime, timezone
from importlib import import_module
from itertools import chain
from weakref import ref as weakref

Expand Down Expand Up @@ -344,6 +347,73 @@ class NestedSetup(StackedObject):
def __init__(self, objects=None):
self.objects = list(objects or ())

@classmethod
def from_dict(cls, config):
"""Create a setup from a configuration mapping.

The optional ``objects`` key contains a list of mappings, in the
same order as the objects passed to the constructor. Each mapping
has a ``class`` key containing a :class:`ContextObject` subclass
or its fully qualified name, such as ``"logbook.StderrHandler"``.
Remaining keys are passed unchanged as keyword arguments.

This does not bind the setup to a stack. Use the returned setup as
a context manager or call :meth:`push_application` explicitly.
The input mappings are not modified.

Only load trusted configurations: resolving classes imports Python
modules and constructing them can execute arbitrary code.

See :ref:`configuration-from-dictionaries` for dictionary and file
examples.
"""
if not isinstance(config, Mapping):
raise TypeError("config must be a mapping")
unknown_keys = config.keys() - {"objects"}
if unknown_keys:
raise ValueError(f"unknown configuration key: {next(iter(unknown_keys))!r}")
specs = config.get("objects", [])
if not isinstance(specs, (list, tuple)):
raise TypeError("objects must be a list or tuple")

constructors = []
for index, spec in enumerate(specs):
if not isinstance(spec, Mapping):
raise TypeError(f"objects[{index}] must be a mapping")
kwargs = dict(spec)
if "class" not in kwargs:
raise ValueError(f"objects[{index}] is missing 'class'")
object_class = kwargs.pop("class")
if isinstance(object_class, str):
module_name, separator, class_name = object_class.rpartition(".")
if not separator or not module_name or not class_name:
raise ValueError(
f"objects[{index}].class must be a fully qualified name"
)
object_class = getattr(import_module(module_name), class_name)
if not isinstance(object_class, type) or not issubclass(
object_class, ContextObject
):
raise TypeError(
f"objects[{index}].class must be a ContextObject subclass"
)
constructors.append((object_class, kwargs))

objects = []
try:
for object_class, kwargs in constructors:
objects.append(object_class(**kwargs))
return cls(objects)
except BaseException:
# A later constructor may fail after a handler has opened a file.
# Preserve that error even if closing one of the handlers fails.
for obj in reversed(objects):
with suppress(Exception):
close = getattr(obj, "close", None)
if close is not None:
close()
raise

def push_application(self):
for obj in self.objects:
obj.push_application()
Expand Down
Loading