maestral.logging

This module defines custom logging records and handlers.

Module Contents

maestral.logging.LOG_FMT_LONG

maestral.logging.LOG_FMT_SHORT

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

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()

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

Return type:

str

class maestral.logging.AwaitableHandler(level=logging.NOTSET, max_unblock_per_second=1)

Bases: logging.Handler

Handler with a blocking API to wait for emits

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.

• max_unblock_per_second (int | None) – Maximum number of times per second to unblock.

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.

Parameters:

record (logging.LogRecord)

Return type:

None

wait_for_emit(timeout)

Blocks until a new record is emitted. This is effectively a longpoll API. Will unblock at max_unblock_per_second.

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

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

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]

emit(record)

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

Parameters:

record (logging.LogRecord) – Log record.

Return type:

None

get_last_message()

Returns:

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

Return type:

str

get_all_messages()

Returns:

A list of all record messages.

Return type:

list[str]

clear()

Clears all cached records.

Return type:

None

class maestral.logging.SdNotificationHandler(level=NOTSET)

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

emit(record)

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')

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')

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)

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]