Core Interface¶
This implements the core interface.
-
class
logbook.base.
Logger
(name=None, level=0)[source]¶ Instances of the Logger class represent a single logging channel. A “logging channel” indicates an area of an application. Exactly how an “area” is defined is up to the application developer.
Names used by logbook should be descriptive and are intended for user display, not for filtering. Filtering should happen based on the context information instead.
A logger internally is a subclass of a
RecordDispatcher
that implements the actual logic. If you want to implement a custom logger class, have a look at the interface of that class as well.-
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()
).
-
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 toCRITICAL
.
-
debug
(*args, **kwargs)¶ Logs a
LogRecord
with the level set toDEBUG
.
-
error
(*args, **kwargs)¶ Logs a
LogRecord
with the level set toERROR
.
-
exception
(*args, **kwargs)¶ Works exactly like
error()
just that the message is optional and exception information is recorded.
-
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()
).
-
info
(*args, **kwargs)¶ Logs a
LogRecord
with the level set toINFO
.
-
level_name
¶ The level as unicode string
-
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.
-
make_record_and_handle
(level, msg, args, kwargs, exc_info, extra)¶ Creates a record from some given arguments and heads it over to the handling system.
-
notice
(*args, **kwargs)¶ Logs a
LogRecord
with the level set toNOTICE
.
-
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.
-
-
class
logbook.base.
LoggerGroup
(loggers=None, level=0, processor=None)[source]¶ A LoggerGroup represents a group of loggers. It cannot emit log messages on its own but it can be used to set the disabled flag and log level of all loggers in the group.
Furthermore the
process_record()
method of the group is called by any logger in the group which by default calls into theprocessor
callback function.-
disabled
= None¶ the disabled flag for all loggers in the group, unless the loggers overrode the setting.
-
level
= None¶ the level of the group. This is reflected to the loggers in the group unless they overrode the setting.
-
loggers
= None¶ a list of all loggers on the logger group. Use the
add_logger()
andremove_logger()
methods to add or remove loggers from this list.
-
process_record
(record)[source]¶ Like
Logger.process_record()
but for all loggers in the group. By default this calls into theprocessor
function is it’s not None.
-
processor
= None¶ an optional callback function that is executed to process the log records of all loggers in the group.
-
-
class
logbook.base.
LogRecord
(channel, level, msg, args=None, kwargs=None, exc_info=None, extra=None, frame=None, dispatcher=None)[source]¶ A LogRecord instance represents an event being logged.
LogRecord instances are created every time something is logged. They contain all the information pertinent to the event being logged. The main information passed in is in msg and args
-
args
= None¶ the positional arguments for the format string.
-
calling_frame
[source]¶ The frame in which the record has been created. This only exists for as long the log record is not closed.
-
channel
= None¶ the name of the logger that created it or any other textual channel description. This is a descriptive name and can be used for filtering.
-
close
()[source]¶ Closes the log record. This will set the frame and calling frame to None and frame-related information will no longer be available unless it was pulled in first (
pull_information()
). This makes a log record safe for pickling and will clean up memory that might be still referenced by the frames.
-
dispatcher
¶ The dispatcher that created the log record. Might not exist because a log record does not have to be created from a logger or other dispatcher to be handled by logbook. If this is set, it will point to an object that implements the
RecordDispatcher
interface.
-
exc_info
= None¶ optional exception information. If set, this is a tuple in the form
(exc_type, exc_value, tb)
as returned bysys.exc_info()
.
-
exception_shortname
¶ An abbreviated exception name (no import path)
-
extra
= None¶ optional extra information as dictionary. This is the place where custom log processors can attach custom context sensitive data.
-
filename
[source]¶ The filename of the module in which the record has been created. Requires a frame or that
pull_information()
was called before.
-
formatted_exception
[source]¶ The formatted exception which caused this record to be created in case there was any.
-
frame
= None¶ If available, optionally the interpreter frame that pulled the heavy init. This usually points to somewhere in the dispatcher. Might not be available for all calls and is removed when the log record is closed.
-
classmethod
from_dict
(d)[source]¶ Creates a log record from an exported dictionary. This also supports JSON exported dictionaries.
-
func_name
[source]¶ The name of the function that triggered the log call if available. Requires a frame or that
pull_information()
was called before.
-
heavy_init
()[source]¶ Does the heavy initialization that could be expensive. This must not be called from a higher stack level than when the log record was created and the later the initialization happens, the more off the date information will be for example.
This is internally used by the record dispatching system and usually something not to worry about.
-
heavy_initialized
= False¶ a flag that is True if the log record is heavy initialized which is not the case by default.
-
information_pulled
= False¶ a flag that is True when all the information was pulled from the information that becomes unavailable on close.
-
keep_open
= False¶ can be overriden by a handler to not close the record. This could lead to memory leaks so it should be used carefully.
-
kwargs
= None¶ the keyword arguments for the format string.
-
late
= False¶ a flag that is True when heavy initialization is no longer possible
-
level
= None¶ the level of the log record as integer.
-
level_name
¶ The level as unicode string
-
lineno
[source]¶ The line number of the file in which the record has been created. Requires a frame or that
pull_information()
was called before.
-
module
[source]¶ The name of the module that triggered the log call if available. Requires a frame or that
pull_information()
was called before.
-
msg
= None¶ The message of the log record as new-style format string.
-
process
= None¶ the PID of the current process
-
pull_information
()[source]¶ A helper function that pulls all frame-related information into the object so that this information is available after the log record was closed.
-
thread
[source]¶ The ident of the thread. This is evaluated late and means that if the log record is passed to another thread,
pull_information()
was called in the old thread.
-
thread_name
[source]¶ The name of the thread. This is evaluated late and means that if the log record is passed to another thread,
pull_information()
was called in the old thread.
-
time
= None¶ the time of the log record creation as
datetime.datetime
object. This information is unavailable until the record was heavy initialized.
-
to_dict
(json_safe=False)[source]¶ Exports the log record into a dictionary without the information that cannot be safely serialized like interpreter frames and tracebacks.
-
update_from_dict
(d)[source]¶ Like the
from_dict()
classmethod, but will update the instance in place. Helpful for constructors.
-
-
class
logbook.base.
Flags
(**flags)[source]¶ Allows flags to be pushed on a flag stack. Currently two flags are available:
- errors
Can be set to override the current error behaviour. This value is used when logging calls fail. The default behaviour is spitting out the stacktrace to stderr but this can be overridden:
'silent'
fail silently 'raise'
raise a catchable exception 'print'
print the stacktrace to stderr (default) - introspection
Can be used to disable frame introspection. This can give a speedup on production systems if you are using a JIT compiled Python interpreter such as pypy. The default is True.
Note that the default setup of some of the handler (mail for instance) includes frame dependent information which will not be available when introspection is disabled.
Example usage:
with Flags(errors='silent'): ...
-
applicationbound
(_cls=<class 'logbook._fallback._StackBound'>)¶ Can be used in combination with the with statement to execute code while the object is bound to the application.
-
pop_application
()¶ Pops the context object from the stack.
-
pop_thread
()¶ Pops the context object from the stack.
-
push_application
()¶ Pushes the context object to the application stack.
-
push_thread
()¶ Pushes the context object to the thread stack.
-
threadbound
(_cls=<class 'logbook._fallback._StackBound'>)¶ Can be used in combination with the with statement to execute code while the object is bound to the thread.
-
class
logbook.base.
Processor
(callback=None)[source]¶ Can be pushed to a stack to inject additional information into a log record as necessary:
def inject_ip(record): record.extra['ip'] = '127.0.0.1' with Processor(inject_ip): ...
-
applicationbound
(_cls=<class 'logbook._fallback._StackBound'>)¶ Can be used in combination with the with statement to execute code while the object is bound to the application.
-
callback
= None¶ the callback that was passed to the constructor
-
pop_application
()¶ Pops the context object from the stack.
-
pop_thread
()¶ Pops the context object from the stack.
-
process
(record)[source]¶ Called with the log record that should be overridden. The default implementation calls
callback
if it is not None.
-
push_application
()¶ Pushes the context object to the application stack.
-
push_thread
()¶ Pushes the context object to the thread stack.
-
threadbound
(_cls=<class 'logbook._fallback._StackBound'>)¶ Can be used in combination with the with statement to execute code while the object is bound to the thread.
-