Logging
*******

Functions to aid library logging. The default logging "Runlevel" is
usually NOTICE and above.

**Stem users are more than welcome to listen for stem events, but
these functions are not being vended to our users. They may change in
the future, use them at your own risk.**

**Module Overview:**

   get_logger - provides the stem's Logger instance
   logging_level - converts a runlevel to its logging number
   escape - escapes special characters in a message in preparation for logging

   log - logs a message at the given runlevel
   log_once - logs a message, deduplicating if it has already been logged
   trace - logs a message at the TRACE runlevel
   debug - logs a message at the DEBUG runlevel
   info - logs a message at the INFO runlevel
   notice - logs a message at the NOTICE runlevel
   warn - logs a message at the WARN runlevel
   error - logs a message at the ERROR runlevel

   LogBuffer - Buffers logged events so they can be iterated over.
     |- is_empty - checks if there's events in our buffer
     +- __iter__ - iterates over and removes the buffered events

   log_to_stdout - reports further logged events to stdout

stem.util.log.Runlevel(enum)

   Enumeration for logging runlevels.

   +------------+--------------------------------------------------------------+
   | Runlevel   | Description                                                  |
   +============+==============================================================+
   | **ERROR**  | critical issue occurred, the user needs to be notified       |
   +------------+--------------------------------------------------------------+
   | **WARN**   | non-critical issue occurred that the user should be aware of |
   +------------+--------------------------------------------------------------+
   | **NOTICE** | information that is helpful to the user                      |
   +------------+--------------------------------------------------------------+
   | **INFO**   | high level library activity                                  |
   +------------+--------------------------------------------------------------+
   | **DEBUG**  | low level library activity                                   |
   +------------+--------------------------------------------------------------+
   | **TRACE**  | request/reply logging                                        |
   +------------+--------------------------------------------------------------+

stem.util.log.get_logger()

   Provides the stem logger.

   Returns:
      **logging.Logger** for stem

stem.util.log.logging_level(runlevel)

   Translates a runlevel into the value expected by the logging
   module.

   Parameters:
      **runlevel** (*stem.util.log.Runlevel*) – runlevel to be
      returned, no logging if **None**

stem.util.log.is_tracing()

   Checks if we’re logging at the trace runlevel.

   New in version 1.6.0.

   Returns:
      **True** if we’re logging at the trace runlevel and **False**
      otherwise

stem.util.log.escape(message)

   Escapes specific sequences for logging (newlines, tabs, carriage
   returns). If the input is **bytes** then this converts it to
   **unicode** under python 3.x.

   Parameters:
      **message** (*str*) – string to be escaped

   Returns:
      str that is escaped

stem.util.log.log(runlevel, message)

   Logs a message at the given runlevel.

   Parameters:
      * **runlevel** (*stem.util.log.Runlevel*) – runlevel to log
        the message at, logging is skipped if **None**

      * **message** (*str*) – message to be logged

stem.util.log.log_once(message_id, runlevel, message)

   Logs a message at the given runlevel. If a message with this ID has
   already been logged then this is a no-op.

   Parameters:
      * **message_id** (*str*) – unique message identifier to
        deduplicate on

      * **runlevel** (*stem.util.log.Runlevel*) – runlevel to log
        the message at, logging is skipped if **None**

      * **message** (*str*) – message to be logged

   Returns:
      **True** if we log the message, **False** otherwise

stem.util.log.trace(message)

stem.util.log.debug(message)

stem.util.log.info(message)

stem.util.log.notice(message)

stem.util.log.warn(message)

stem.util.log.error(message)

class stem.util.log.LogBuffer(runlevel, yield_records=False)

   Bases: "logging.Handler"

   Basic log handler that listens for stem events and stores them so
   they can be read later. Log entries are cleared as they are read.

   Changed in version 1.4.0: Added the yield_records argument.

   Deprecated since version 1.8.0: This will be dropped in Stem 2.x.
   Use python’s logging.BufferingHandler instead.

   is_empty()

   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.

stem.util.log.log_to_stdout(runlevel)

   Logs further events to stdout.

   Parameters:
      **runlevel** (*stem.util.log.Runlevel*) – minimum runlevel a
      message needs to be to be logged
