kibot.logger | index /usr/src/rpm/BUILD/kibot-0.0.12/kibot/logger.py |
A module for convenient yet powerful file-object logging
BASIC USAGE
from logger import Logger
log = Logger(threshold=0) # create the log object and give it
# a threshold of 0
log.log(2, 'all done') # send a log of priority 2 (not printed)
log(0, 'error: bandits!') # send a log of priority 0 (printed)
log.write(0, stringvar) # do a raw write on the file object
DESCRIPTION
Each logging object is given a threshold. Any messages that are
then sent to that object are logged only if their priority meets or
exceeds the threshold. Lower numerical priority means that a
message is more important. For example: if a log object has
threshold 2, then all messages of priority 2, 1, 0, -1, etc will be
logged, while those of priority 3, 4, etc. will not. I suggest the
following scale:
LOG PRIORITY MEANING
-1 failure - cannot be ignored
0 important message - printed in default mode
1 informational message - printed with -v
2 debugging information
THRESHOLD MEANING
-1 quiet mode (-q) only failures are printed
0 normal operation
1 verbose mode (-v)
2 debug mode (-vv or -d)
It can be extended farther in both directions, but that is rarely
useful. It can also be shifted in either direction. This might be
useful if you want o supply the threshold directly on the command
line but have trouble passing in negative numbers. In that case,
add 1 to all thresholds and priorities listed above.
BASIC OPTIONS
There are a couple of basic options that are commonly needed. These
are attribues of instances of class Logger.
preprefix
Text that will be printed at the start of each line of output (for
log()ged, not write()en messages). This might be your program's
name, for example.
log.preprefix = 'myprog'
If preprefix is callable, then it will be called for each log and
the returned value will be used. This is useful for printing the
current time.
import time
def printtime():
return time.strftime('%m/%d/%y %H:%M:%S ',
time.localtime(time.time()))
log.preprefix = printtime
file_object
This is the file object to which output is directed.
LOG CONTAINERS
If you want a program to log to multiple destinations, it might be
convenient to use log containers. A log container is an object
which hold several log objects. When you log to a log container it
passes the message on (with optional tests) to each of the log
objects it contains. For example:
from logger import Logger, LogContainer
system = Logger(threshold=1, file_object=logfile)
debug = Logger(threshold=5, file_object=sys.stdout)
log = LogContainer([system, debug])
log(3, 'sent to system and debug, but only debug will print it')
log(0, 'very important, both will print it')
In this mode, log containers are just shorthand for calling all
contained objects with the same priority and message.
When a log object is held in a container, it can still be used
directly. For example, you can still do
debug(3, ['this will not be sent to the system log, even if its',
' threshold is set very high'])
(Yes, you can send lists of strings and they will be formatted on
different lines. It is pretty smart.)
ADVANCED
There are a number of options available for both classes. These are
documented below, in the respective classes and methods. Here is a
list of some of the things you can do:
* make the prefix contain a string which gets repeated for more
important logs. (prefix)
* directly test if a log object WOULD log, so you can do
complicated stuff, like efficient for loops. (test)
* make the priority, threshold arbitrary objects, with a
home-rolled test to see if it should log. (test)
* give log containers a "master threshold" and define arbitrary
behavior based on it. Examples include:
- only pass on messages of sufficient priority (ragardless of
the thresholds of the log ojects).
- only pass on messages to objects whose thresholds are
(numerically) lower than the master threshold.
SEE ALSO
Take a look at the examples at the end of this file in the test &
demo section.
COMMENTS
I welcome comments, questions, bug reports and requests... I'm very
lonely. :)
Modules | ||||||
|
Classes | ||||||||||||||||
|
Data | ||
AUTHOR = 'Michael D. Stenner <mstenner@phy.duke.edu>' DATE = '2002/06/07' VERSION = '0.4' |