Logbook

A simple Qt widget to improve the pleasure of reading log messages.

Table of Contents

• Logging
• Prerequisites
• The Interface
• Communication
• Customization
  • Attributes
  • Formatting
  • Custom Levels
  • Exception ToolTips
  • Custom Signals

Logging

The Logging module is awesome! However, if multiple people/tools setup numerous loggers and handlers, it can make reading and filtering log messages hard.

---

Prerequisites

You need to ensure the Qt.py wrapper is available, which supports PySide2, PyQt5, PySide and PyQt4.

---

The Logbook graphical user interface

The Logbook user interface is focused on making it simple for you, to search for information quickly.

It exposes

• an arbitrary number of checkable buttons for defined log levels
• a checkbox to enable corresponding background colors per record item
• a field for a filter regular expression
• the actual list that holds the catched log records
• a button to clear this list

---

Let your loggers communicate with the Logbook

To catch log records you only have to attach the provided Logbook handler to your loggers of choice.

import logging

from logbook import LogbookWidget

# acquire a logger
my_logger = logging.getLogger("foo")
my_logbook_instance = LogbookWidget()

# the `handler` property holds the required handler
my_logger.addHandler(my_logbook_instance.handler)

# show the logbook gui
my_logbook_instance.show()

As soon as your handler was attached, the log records will be catched within a background thread to keep the UI respsonsive.

---

Customization

Attributes

Attribute	Type	Description
FLAGS	bytemask	Set different logbook behaviors that can be combined.
LEVEL_BUTTON_WIDTH	int	Defines the width of the level buttons.
LOG_LEVELS	list	A list with levels that will correspond to the checkable level buttons that will be added. default: ["debug", "info", "warning", "error", "critical"]. When changed the LEVEL_VALUES and LEVEL_COLORS attribute needs to be adjusted too.
LEVEL_VALUES	dict	A dictionary with corresponding level numbers to the defined LOG_LEVELS. default: {"debug": 10, "info": 20, "warning": 30, error: "40", "critical": 50}.
LEVEL_COLORS	dict	A dictionary with corresponding colors to the defined LOG_LEVELS. Expects RGB values from 0-255 and an optional alpha value from 0-100. default: "debug": (255, 255, 255, 100), "info": (204, 236, 242, 100), "warning": (152, 210, 217, 100), "error": (223, 57, 57, 100), "critical": (182, 60, 66, 100)}
INITIAL_FILTER_REGEX	str	A regular expression that will be used when launching the logbook.
INITIAL_COLORING	bool	If True coloring mode will be enabled by default when launching the logbook.
EXCEPTION_FORMATTER	logging.Formatter	A formatter instance that will be used to format the exc_info tuple that will be dispayed inside the ToolTips of recorditems.

Flag	Description
COLORING_TEXT	When given the item's foreground color will be set instead of the background color.
IGNORE_FORMATTER	If a formatter was set to the handler, it can be explicitly ignored by setting using this. It means, the formatter will not be considered as the recorditem's text. Instead it will only use the LogRecord.getMessage() directly.
INITIAL_COLORING	When given the Coloring option will be checked by default when launching the logbook.
READABLE_TEXT_COLOR	When given and COLORING_TEXT is NOT set it sets an automatic item foreground color based on the background color for better readability.
RE_IGNORE_CASE	When given the Ignore Case option will be checked by default when launching the logbook.

This examples activates coloring of item's foreground color instead of background color.

LogbookWidget.FLAGS = LogbookWidget.Flags.INITIAL_COLORING | LogbookWidget.Flags.COLORING_TEXT

Recorditems Formatting

By default, the logbook handlers doesn't use a formatter. It will use the LogRecord.getMessage() attribute as the recorditem's text. A formatter can be set easily by using the handler property on the logbook instance.

my_logbook.handler.setFormatter("%(asctime)s %(message)s")

Custom Levels

You can provide custom levels for the Logbook.

from logbook import LogbookWidget

# the order inside the `LOG_LEVELS` list matters, the buttons will be added from left to right
# we would like to introduce the "paranoid" level, that is below `logging.DEBUG`
LogbookWidget.LOG_LEVELS.insert(0, "paranoid")
# a corresponding level and color must be defined
LogbookWidget.LEVEL_VALUES["paranoid"] = 5
# an alpha value is optional
LogbookWidget.LEVEL_COLORS["paranoid"] = (125, 80, 125)

Exception ToolTips

Whenever a catched LogRecord includes an exc_info tuple, it will display a ToolTip with the underlying exception. By default logging.Formatter().formatException(record) will be used to format the exception. However a custom formatter can be set via EXCEPTION_FORMATTER attribute.

from logging import Formatter

from logbook import LogbookWidget

class MyExceptionFormatter(Formatter):
    def formatException(exc_info):
        # setup the actual formatting here

# override the formatter used to format the underlying exception info tuple
LogbookWidget.EXCEPTION_FORMATTER = MyExceptionFormatter()

Custom Signals

The following signals can be connected to extend functionality of the loogbook.

# example shows how to call a custom QMenu
# the event gets triggered via RMB click on a LogRecordItem
# it will pass the global cursor position, a list of underlying/selected `LogRecordItem` instances 
# and the LogRecordsListWidget

class MyMenu(QtWidgets.QMenu):
    def __init__(self, pos, record_items, records_list_widget):
        super(MyMenu, self).__init__()
        for record_item in record_items:
            self.addAction("{}| {}".format(record_item.record.levelname, record_item.record.msg))
        self.exec_(pos)

my_logbook_instance.signals.record_context_request.connect(MyMenu)