# Logbook

# Internal API

This documents the internal API that might be useful for more advanced setups or custom handlers.

logbook.base.dispatch_record(record)

  Passes a record on to the handlers on the stack. This is useful when log records are created programmatically and already have all the information attached and should be dispatched independent of a logger.

class logbook.base.StackedObject

  Base class for all objects that provide stack manipulation operations.

  applicationbound()

    Can be used in combination with the with statement to execute code while the object is bound to the application.

  contextbound()

    Can be used in combination with the with statement to execute code while the object is bound to the asyncio context.

  greenletbound()

    Can be used in combination with the with statement to execute code while the object is bound to the greenlet.

  pop_application()

    Pops the stacked object from the application stack.

  pop_context()

    Pops the stacked object from the asyncio (via contextvar) stack.

  pop_greenlet()

    Pops the stacked object from the greenlet stack.

  pop_thread()

    Pops the stacked object from the thread stack.

  push_application()

    Pushes the stacked object to the application stack.

  push_context()

    Pushes the stacked object to the asyncio (via contextvar) stack.

  push_greenlet()

    Pushes the stacked object to the greenlet stack.

  push_thread()

    Pushes the stacked object to the thread stack.

  threadbound()

    Can be used in combination with the with statement to execute code while the object is bound to the thread.

class logbook.base.RecordDispatcher(name=None, level=0)

  A record dispatcher is the internal base class that implements the logic used by the `Logger`.

  call_handlers(record)

    Pass a record to all relevant handlers in the following order:

    - per-dispatcher handlers are handled first

    - afterwards all the current context handlers in the order they were pushed

    Before the first handler is invoked, the record is processed (`process_record()`).

  group

    optionally the name of the group this logger belongs to

  handle(record)

    Call the handlers for the specified record. This is invoked automatically when a record should be handled. The default implementation checks if the dispatcher is disabled and if the record level is greater than the level of the record dispatcher. In that case it will call the handlers (`call_handlers()`).

  handlers

    list of handlers specific for this record dispatcher

  level

    the level of the record dispatcher as integer

  make_record_and_handle(level, msg, args, kwargs, exc_info, extra, frame_correction)

    Creates a record from some given arguments and heads it over to the handling system.

  name

    the name of the record dispatcher

  process_record(record)

    Processes the record with all context specific processors. This can be overriden to also inject additional information as necessary that can be provided by this record dispatcher.

  suppress_dispatcher = False

    If this is set to True the dispatcher information will be suppressed for log records emitted from this logger.

class logbook.base.LoggerMixin

  This mixin class defines and implements the “usual” logger interface (i.e. the descriptive logging functions).

  Classes using this mixin have to implement a `handle()` method which takes a `LogRecord` and passes it along.

  catch_exceptions(*args, **kwargs)

    A context manager that catches exceptions and calls `exception()` for exceptions caught that way. Example:

        with logger.catch_exceptions():
            execute_code_that_might_fail()

  critical(*args, **kwargs)

    Logs a `LogRecord` with the level set to `CRITICAL`.

  debug(*args, **kwargs)

    Logs a `LogRecord` with the level set to `DEBUG`.

  disable()

    Convenience method to disable this logger.

    Raises

      AttributeError – The disabled property is read-only, typically because it was overridden in a subclass.

    New in version 1.0.

  enable()

    Convenience method to enable this logger.

    Raises

      AttributeError – The disabled property is read-only, typically because it was overridden in a subclass.

    New in version 1.0.

  error(*args, **kwargs)

    Logs a `LogRecord` with the level set to `ERROR`.

  exception(*args, **kwargs)

    Works exactly like `error()` just that the message is optional and exception information is recorded.

  info(*args, **kwargs)

    Logs a `LogRecord` with the level set to `INFO`.

  property level_name

    The name of the minimium logging level required for records to be created.

  log(level, *args, **kwargs)

    Logs a `LogRecord` with the level set to the level parameter. Because custom levels are not supported by logbook, this method is mainly used to avoid the use of reflection (e.g.: `getattr()`) for programmatic logging.

  notice(*args, **kwargs)

    Logs a `LogRecord` with the level set to `NOTICE`.

  trace(*args, **kwargs)

    Logs a `LogRecord` with the level set to `TRACE`.

  warn(*args, **kwargs)

    Logs a `LogRecord` with the level set to `WARNING`. This function has an alias named `warning()`.

  warning(*args, **kwargs)

    Alias for `warn()`.

class logbook.handlers.StringFormatterHandlerMixin(format_string)

  A mixin for handlers that provides a default integration for the `StringFormatter` class. This is used for all handlers by default that log text to a destination.

  default_format_string = '[{record.time:%Y-%m-%d %H:%M:%S.%f%z}] {record.level_name}: {record.channel}: {record.message}'

    a class attribute for the default format string to use if the constructor was invoked with None.

  property format_string

    the currently attached format string as new-style format string.

  formatter_class

    the class to be used for string formatting

    alias of `logbook.handlers.StringFormatter`