maestral.logging

This module defines custom logging records and handlers.

Module Contents

maestral.logging.LOG_FMT_LONG[source]
maestral.logging.LOG_FMT_SHORT[source]
class maestral.logging.EncodingSafeLogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None, **kwargs)[source]

Bases: logging.LogRecord

A log record which ensures that messages contain only unicode characters

This is useful when log messages may contain file paths generates by OS APIs. In Python, such path strings may contain surrogate escapes and will therefore raise a UnicodeEncodeError under many circumstances (printing to stdout, etc.).

getMessage()[source]

Formats the log message and replaces all surrogate escapes with “�”.

Return type

str

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(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(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()[source]
Returns

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

Return type

str

getAllMessages()[source]
Returns

A list of all record messages.

Return type

list[str]

clear()[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(record)[source]

Sends the record message to systemd as service status.

Parameters

record (logging.LogRecord) – Log record.

Return type

None

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

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

Parameters

  • module_name (str) – Module name.

  • config_name (str) – Config name.

Returns

Scoped logger name.

Return type

str

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, file=True, stderr=True, journal=True, status=True)[source]

Set up loging to external channels. Systemd-related logging will fail silently if the current process was not started by systemd.

Parameters

  • config_name (str) – Config name to determine log level and namespace for loggers. See scoped_logger_name() for how the logger name is determined.

  • file (bool) – Whether to log to files.

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

  • journal (bool) – Whether to log to the systemd journal.

  • status (bool) – Whether to log to the systemd status notifier. Note that this will always be performed at level INFO.

Returns

Log handlers.

Return type

Sequence[logging.Handler]