This module defines custom logging records and handlers.

Module Contents

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


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

class maestral.logging.CachedHandler(level: int = logging.NOTSET, maxlen: Optional[int] = 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.

  • level – Initial log level. Defaults to NOTSET.

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

cached_records :Deque[logging.LogRecord][source]
emit(self, record: logging.LogRecord)None[source]

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


record – Log record.

wait_for_emit(self, timeout: Optional[float])bool[source]

Blocks until a new record is emitted.


timeout – Maximum time to block before returning.


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


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


A list of all record messages.


Clears all cached records.

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.

emit(self, record: logging.LogRecord)None[source]

Sends the record massage to systemd as service status.


record – Log record.