commit 1e04a08e75ae73f204c6ba3d4f8eef33104973f5 Author: Damian Johnson atagar@torproject.org Date: Tue Jun 5 19:40:57 2012 -0700

Converting stem.util.log to reStructuredText --- stem/util/log.py | 86 +++++++++++++++++++++++++----------------------------- 1 files changed, 40 insertions(+), 46 deletions(-)

diff --git a/stem/util/log.py b/stem/util/log.py index a25e3fd..59c4a85 100644 --- a/stem/util/log.py +++ b/stem/util/log.py @@ -2,31 +2,35 @@ Functions to aid library logging. Default logging is usually NOTICE and above, runlevels being used as follows...

- ERROR - critical issue occured, the user needs to be notified - WARN - non-critical issue occured 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 - -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 +* **ERROR** - critical issue occured, the user needs to be notified +* **WARN** - non-critical issue occured 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 + +**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 """

import logging @@ -75,8 +79,7 @@ def get_logger(): """ Provides the stem logger.

- Returns: - logging.Logger for stem + :return: logging.Logger for stem """

return LOGGER @@ -85,8 +88,7 @@ def logging_level(runlevel): """ Translates a runlevel into the value expected by the logging module.

- Arguments: - runlevel (Runlevel) - runlevel to be returned, no logging if None + :param Runlevel runlevel: runlevel to be returned, no logging if ``None`` """

if runlevel: return LOG_VALUES[runlevel] @@ -96,11 +98,9 @@ def escape(message): """ Escapes specific sequences for logging (newlines, tabs, carrage returns).

- Arguments: - message (str) - string to be escaped + :param str message: string to be escaped

- Returns: - str that is escaped + :returns: str that is escaped """

for pattern, replacement in (("\n", "\n"), ("\r", "\r"), ("\t", "\t")): @@ -112,10 +112,8 @@ def log(runlevel, message): """ Logs a message at the given runlevel.

- Arguments: - runlevel (Runlevel) - runlevel to log the message at, logging is skipped if - None - message (str) - message to be logged + :param Runlevel runlevel: runlevel to log the message at, logging is skipped if ``None`` + :param str message: message to be logged """

if runlevel: @@ -126,14 +124,11 @@ def 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.

- Arguments: - message_id (str) - unique message identifier to deduplicate on - runlevel (Runlevel) - runlevel to log the message at, logging is skipped if - None - message (str) - message to be logged + :param str message_id: unique message identifier to deduplicate on + :param Runlevel runlevel: runlevel to log the message at, logging is skipped if ``None`` + :param str message: message to be logged

- Returns: - True if we log the message, False otherwise + :returns: True if we log the message, False otherwise """

if not runlevel or message_id in DEDUPLICATION_MESSAGE_IDS: @@ -178,8 +173,7 @@ def log_to_stdout(runlevel): """ Logs further events to stdout.

- Arguments: - runlevel (Runlevel) - minimum runlevel a message needs to be to be logged + :param Runlevel runlevel: minimum runlevel a message needs to be to be logged """

logging.basicConfig(