Usage¶
This library allows you to forward logs from the python side to the GLib
side and the other way around.
You can even forward logs to Python but still use GLib writer functions, such
as forwarding to journald
.
Depending what you do, look at the correct chapter of what you want to do.
Forward GLib → Python¶
To be written.
Quick usage:
from gi.repository import GLib
import glib_log_bridge.glib2python as glib2python
g2plog = glib2python.Logger()
GLib.log_set_writer_func(g2plog.logWriterFunc, None)
After importing, glib_log_bridge.glib2python.Logger
is being
instantiated, which accepts the log messages and forwards them to the
Python Logger.
The glib_log_bridge.glib2python.Logger.logWriterFunc()
is the actual
writer function that is then passed to GLib.log_set_writer_func()
to actually receive the messages and forward them.
The userdata-parameter is ignored, so it can be anything, or simply None
.
Customizing¶
To be written.
Respect G_MESSAGES_DEBUG
¶
To be written.
The filter glib_log_bridge.glib2python.FilterGLibMessagesDebug
respects the G_MESSAGES_DEBUG
environment variable by only forwarding
debug messages if the logger names appears in them (space-separated, and
dash-separated “namespaces”) or all
has been specified.
This can then be applied to an logging.Logger
or
logging.Handler
via the logging.Logger.addFilter()
or logging.Handler.addFilter()
methods.
Note
G_MESSAGES_DEBUG
is being converted by replacing the dashes
to dots, since dashes are used in the GLib world to separate namespaces,
but dots in the Python world.
Warning
Filters don’t get propagated when applied to a logger
(so filters for the root logger get ignored by the "GLib"
-logger).
Because of that, better apply it to the handler instead.
Warning
Since the filters need to get the debug messages, you should set the
log level of the logging.Logger
and logging.Handler
to logging.DEBUG
or lower, so they can be processed by
the filter.
Alternatively, instead of applying a filter, you can use
glib_log_bridge.glib2python.FilterGLibMessagesDebug.register_loggers()
which registers the filter as well as set the log level of all loggers
specified in G_MESSAGES_DEBUG
(or just the root logger when all
is
specified).
This as the feature that logging.Logger.isEnabledFor()
will properly
work for logging.DEBUG
, which can be used to do some more costly
operations when debugging.
Forward Python → GLib¶
To be written.
Quick usage:
import logging
import glib_log_bridge.python2glib as python2glib
handler = python2glib.LoggerHandler()
logging.getLogger().addHandler(handler)
# Logger to apply, logger.getLogger() does it for all messages
After importing, an normal glib_log_bridge.python2glib.LoggerHandler
is being instantiated, which accepts the log messages from a logger and forwards
them to GLib.
To register the handler, you need to use logging.Logger.addHandler()
method on a logging.Logger
.
You most likely want to use the root logger logging.getLogger()
,
so all logs are forwarded.
Alternatively, you can forward a specific logger. Note that the full logger name is being used and converted to GLib format (that uses dashes instead of dots), so usually you don’t need to do anything special if you just want to forward one logger (such as only forward the logs done by the application itself).
Customizing¶
To be written.
You can create a custom logging.Filter
and add them via
logging.Handler.addFilter
to the
glib_log_bridge.python2glib.LoggerHandler
if you want to determine
which exact messages should be forwarded.
Directly use a GLib writer/handler¶
The classes glib_log_bridge.python2glib.GLibWriterHandler
and
glib_log_bridge.python2glib.GLibLogHandler
are like
glib_log_bridge.python2glib.LoggerHandler
, but instead forward
to an GLib-compatible GLib.LogWriterFunc
or Glib.LogFunc
.
They accept the corresponding function (and userdata) as the parameters
when instantiating:
glibWriterHandlerDefault = GLibWriterHandler(GLib.log_writer_default)
Warning
glib_log_bridge.python2glib.GLibLogHandler
uses the old
non-structured GLib logging API, which only accepts the log domain,
log level and the message itself. Other fields/information are dropped
silently.
Instead please use
glib_log_bridge.python2glib.GLibWriterHandler
,
which uses the newer structured GLib logging API and thus does not
drop the additional fields.
There are pre-existing instances using the default writers GLib provides:
glib_log_bridge.python2glib.glibWriterHandlerDefault
(usesGLib.log_writer_default()
)glib_log_bridge.python2glib.glibWriterHandlerStandardStreams
(usesGLib.log_writer_standard_streams()
)glib_log_bridge.python2glib.glibWriterHandlerJournald
(usesGLib.log_writer_journald()
)glib_log_bridge.python2glib.glibLogHandlerDefault
(usesGLib.log_default_handler()
, not recommended as per the warning above)
For example, if you want to forward to jorunald
, you can do:
logging.getLogger().addHandler(python2glib.glibWriterHandlerJournald)