maestral.logging

This module defines custom logging records and handlers.

Module Contents

class maestral.logging.CachedHandler(level=logging.NOTSET, maxlen=None)[source]

Bases: logging.Handler

Handler which stores past records

This is used to populate Maestral’s status and error interfaces. The method wait_for_emit() can be used from another thread to block until a new record is emitted, for instance to react to state changes.

Parameters

  • level (int) – Initial log level. Defaults to NOTSET.

  • maxlen (int | None) – Maximum number of records to store. If None, all records will be stored. Defaults to None.

cached_records :collections.deque[logging.LogRecord][source]
emit(self, record)[source]

Logs the specified log record and saves it to the cache.

Parameters

record (logging.LogRecord) – Log record.

Return type

None

wait_for_emit(self, timeout)[source]

Blocks until a new record is emitted. This is effectively a longpoll API.

Parameters

timeout (float | None) – Maximum time to block before returning.

Returns

True if there was a status change, False in case of a timeout.

Return type

bool

getLastMessage(self)[source]
Returns

The log message of the last record or an empty string.

Return type

str

getAllMessages(self)[source]
Returns

A list of all record messages.

Return type

list[str]

clear(self)[source]

Clears all cached records.

Return type

None

class maestral.logging.SdNotificationHandler(level=NOTSET)[source]

Bases: logging.Handler

Handler which emits messages as systemd notifications

This is useful when used from a systemd service and will do nothing when no NOTIFY_SOCKET is provided.

notifier[source]
emit(self, record)[source]

Sends the record massage to systemd as service status.

Parameters

record (logging.LogRecord) – Log record.

Return type

None

maestral.logging.scoped_logger(module_name, config_name='maestral')[source]

Returns a logger for the module module_name, scoped to the given config.

Parameters

  • module_name (str) – Module name.

  • config_name (str) – Config name.

Returns

Logger instances scoped to the config.

Return type

logging.Logger

maestral.logging.setup_logging(config_name, log_to_stderr=True)[source]

Sets up logging handlers for the given config name. The following handlers are installed for the root logger:

  • RotatingFileHandler: Writes logs to the appropriate log file for the config. Log level is determined by the config value.

  • StreamHandler: Writes logs to stderr. Log level is determined by the config value. This will be replaced by a null handler if log_to_stderr is False.

  • SdNotificationHandler: Sends all log messages of level INFO and higher to the NOTIFY_SOCKET if provided as an environment variable. The log level is fixed.

  • JournalHandler: Writes logs to the systemd journal. Log level is determined by the config value. Will be replaced by a null handler if not started as a systemd service or if python-systemd is not installed.

Any previous loggers are cleared.

Parameters

  • config_name (str) – The config name.

  • log_to_stderr (bool) – Whether to log to stderr.

Returns

(log_handler_file, log_handler_stream, log_handler_sd, log_handler_journal)

Return type

tuple[logging.handlers.RotatingFileHandler, logging.StreamHandler | logging.NullHandler, SdNotificationHandler, journal.JournalHandler | logging.NullHandler]