LSL Logger

Centralized logging for LSL, built on Python’s logging module. Provides a shared logger instance, threaded handler support for GUI integration, and convenience functions for console/file logging.

lsl.logger.LSL_LOGGER = <Logger lsl_logger (INFO)>

The LSL logger instance that users should use

lsl.logger.LSL_LOG_FORMAT = <logging.Formatter object>

Default LSL_LOGGER entry formatter

lsl.logger.LSL_LOG_QUEUE = <queue.Queue object>

Default queue for added log entries across threads with the ThreadedHandler

lsl.logger.NOTE = 25

Custom logging level for LSL notes. Sits between INFO (20) and WARNING (30) so notes are visible at the default INFO log level but can be visually distinguished from routine INFO messages.

class lsl.logger.ThreadedHandler(level=0)

logging.Handler class that allows messages to be captured in one thread and displayed in another. Useful for powering a GUI a la the CASA logger.

emit(record)

Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.

lsl.logger.add_filter(pattern)

Add a filter to the logger based on a module name pattern (e.g., ‘lsl.imaging.*’, ‘lsl.sim.vis’). Only log records whose name matches the pattern will be processed. Supports shell-style wildcards: ‘*’ matches any sequence, ‘?’ matches one character.

lsl.logger.add_handler(logging_handler, formatter=<logging.Formatter object>)

Add a new handler to the LSL logger. If the formatter keyword is not None then the handler’s formatter will be set before it is added.

lsl.logger.capture_warnings(enable_capture)

Enable (True) or disable (False) capturing warnings.warn() calls into the main LSL logger.

lsl.logger.clear_filters()

Remove all filters from the logger.

lsl.logger.disable_console_logging()

Disable logging to the console.

lsl.logger.disable_file_logging()

Disable logging to a file and close the file handler.

lsl.logger.enable_console_logging(level=None, stream=None)

Enable logging to the console, optionally at a handler-specific logging level (defaults to the logger’s level) and to a given stream (defaults to sys.stderr).

lsl.logger.enable_file_logging(filename, level=None, mode='a')

Enable logging to a file. The handler uses a logging-level of level (defaults to the logger’s level) and opens the file with mode (‘a’ for append, ‘w’ for overwrite).

lsl.logger.get_log_level()

Return the current logging level for the LSL logger.

lsl.logger.make_note(msg, *args, **kwds)

Add a note to the LSL logger instance at the custom NOTE level. Extra arguments are passed through to logging.Logger.log.

lsl.logger.remove_filter(pattern)

Remove a previously added module-name-pattern filter from the logger.

lsl.logger.remove_handler(logging_handler)

Remove the specified handler from the LSL logger.

lsl.logger.set_log_level(logging_level)

Set the logging level for the LSL logger (e.g., logging.DEBUG, logging.INFO, logging.WARNING).

Logger GUI Widgets

Tk-based GUI widgets for displaying LSL logger messages in real-time. Provides LoggerFrame for embedding in existing Tk applications, FilterFrame for controlling log display, and LoggerGUI for standalone use.

class lsl.logger_gui.FilterFrame(frame, logger_frame)

Tk frame for controlling log level, console/file output, and module pattern filtering. Designed to pair with a LoggerFrame.

start()

No-op; provided for interface parity with LoggerFrame.

stop()

No-op; provided for interface parity with LoggerFrame.

class lsl.logger_gui.LoggerFrame(frame, update_interval_ms=100, max_lines=10000)

Tk frame to show log messages from the LSL logger. Attaches a ThreadedHandler to the main LSL logger on initialization.

clear()

Clear the display buffer.

show_at_level(level)

Show/hide log messages by eliding text tags below level.

start()

Start the background queue poller.

stop()

Stop the poller and remove the handler from the LSL logger.

class lsl.logger_gui.LoggerGUI(title='LSL Logger')

Standalone Tk window combining a LoggerFrame and FilterFrame for displaying LSL logger messages. Creates a new Tk root or a Toplevel if one already exists.

quit(*args)

Close the window and clean up handlers.