maestral.logging
================

.. py:module:: maestral.logging

.. autoapi-nested-parse::

   This module defines custom logging records and handlers.









Module Contents
---------------

.. py:data:: LOG_FMT_LONG

.. py:data:: LOG_FMT_SHORT

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

   Bases: :py:obj:`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 :exc:`UnicodeEncodeError` under many circumstances (printing to stdout, etc.).


   .. py:method:: getMessage()

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



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

   Bases: :py:obj:`logging.Handler`


   Handler with a blocking API to wait for emits

   The method :meth:`wait_for_emit` can be used from another thread to block until a
   new record is emitted, for instance to react to state changes.

   :param level: Initial log level. Defaults to NOTSET.
   :param max_unblock_per_second: Maximum number of times per second to unblock.


   .. py:method:: 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.



   .. py:method:: wait_for_emit(timeout)

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

      :param timeout: Maximum time to block before returning.
      :returns: ``True`` if there was a status change, ``False`` in case of a timeout.



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

   Bases: :py:obj:`logging.Handler`


   Handler which stores past records

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

   :param level: Initial log level. Defaults to NOTSET.
   :param maxlen: Maximum number of records to store. If ``None``, all records will be
       stored. Defaults to ``None``.


   .. py:attribute:: cached_records
      :type:  collections.deque[logging.LogRecord]


   .. py:method:: emit(record)

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

      :param record: Log record.



   .. py:method:: get_last_message()

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



   .. py:method:: get_all_messages()

      :returns: A list of all record messages.



   .. py:method:: clear()

      Clears all cached records.



.. py:class:: SdNotificationHandler(level=NOTSET)

   Bases: :py:obj:`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.


   .. py:attribute:: notifier


   .. py:method:: emit(record)

      Sends the record message to systemd as service status.

      :param record: Log record.



.. py:function:: scoped_logger_name(module_name, config_name = 'maestral')

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

   :param module_name: Module name.
   :param config_name: Config name.
   :returns: Scoped logger name.


.. py:function:: scoped_logger(module_name, config_name = 'maestral')

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

   :param module_name: Module name.
   :param config_name: Config name.
   :returns: Logger instances scoped to the config.


.. py:function:: 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.

   :param config_name: Config name to determine log level and namespace for loggers.
       See :meth:`scoped_logger_name` for how the logger name is determined.
   :param file: Whether to log to files.
   :param stderr: Whether to log to stderr.
   :param journal: Whether to log to the systemd journal.
   :param status: Whether to log to the systemd status notifier. Note that this will
       always be performed at level INFO.
   :returns: Log handlers.