|author||Lars Wirzenius <email@example.com>||2011-05-28 17:32:47 +0100|
|committer||Lars Wirzenius <firstname.lastname@example.org>||2011-05-28 17:32:47 +0100|
Update tracing.py docstrings.
1 files changed, 31 insertions, 10 deletions
@@ -15,16 +15,22 @@
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-'''Python debubbing log messages.
+''':mod:`tracing` -- fast debug trace messages
+This module provides fast debugging log messages that can be
+turned on and off during runtime.
-This module provides a couple of functions for logging debug messages.
It is sometimes practical to add a lot of debugging log messages to a
program, but having them enabled all the time results in very large
-log files. Also, logging that much takes quite a bit of time.
+log files. Also, logging that much takes quite a bit of time. Yet,
+keeping the logging statements can be a good idea so that they can
+be enabled if there is a problem that needs debugging, as long as
+there is a way to disable them in normal production mode.
-This module provides a way to turn such debugging or tracing messages
-on and off, based on the filename they occur in. For example:
+This module provides a way to achieve that. For example::
+ # in the main program
@@ -32,13 +38,15 @@ on and off, based on the filename they occur in. For example:
+ # in some other module
- tracing.trace('arg1=%s' % arg1)
- tracing.trace('arg2=%s' % arg2)
+ tracing.trace('arg1=%s', arg1)
+ tracing.trace('arg2=%s', arg2)
-Only calls that happen in files whose names contain 'foobar' or
-'yeehaa' will actually be logged. Pattern matching is based on
-substring checking only, no globbing or regexps, sorry.
+Only calls that happen in files whose names contain ``foobar`` or
+``yeehaa`` will actually be logged. Pattern matching is based on
+substring checking only, for speed, so there is no globbing or
+regular expression matching.
@@ -53,15 +61,28 @@ trace_cache = set()
+ '''Add a module name pattern.'''
+ '''Remove all module name patterns.
+ After this, nothing will be traced. This is also the initial state.
def trace(msg, *args):
+ '''Log a trace message if the calling module's name matches a pattern.
+ If any arguments are given, the message is formatted as if
+ with ``msg % args``, otherwise the message is written out as is.
frames = traceback.extract_stack(limit=2)
filename, lineno, funcname, text = frames