Stem Docs



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

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

Provides the stem logger.

Returns:logging.Logger for stem

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

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

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)[source]

Logs a message at the given runlevel.

  • 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)[source]

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

  • 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

True if we log the message, False otherwise

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

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.


Logs further events to stdout.

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