maestral.logging
¶
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.).
- class maestral.logging.AwaitableHandler(level=logging.NOTSET, max_unblock_per_second=1)[source]¶
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:
- emit(record)[source]¶
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
- 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:
- 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
- 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(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.
- maestral.logging.scoped_logger(module_name, config_name='maestral')[source]¶
Returns a logger for the module
module_name
, scoped to the given config.- Parameters:
- Returns:
Logger instances scoped to the config.
- Return type:
- 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]