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:

For example, if you want to forward to jorunald, you can do:

logging.getLogger().addHandler(python2glib.glibWriterHandlerJournald)