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 LoggerLogContainer
 
    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
       
string
sys

 
Classes
       
LogContainer
Logger

 
class LogContainer
     Methods defined here:
__call__ = log(self, priority, message=None)
__init__(self, list=[], threshold=None, default=1)
add(self, log_obj)
Add a log object to the container.
log(self, priority, message=None)
Log a message to all contained log objects, depending on
the results of test()
test(self, priority, message, threshold, log_obj)
Test which log objects should be passed a given message.
 
This method is used to determine if a given message (and
priority) should be passed on to a given log_obj.  The
container's threshold is also provided.
 
This method always returns 1, and is the default, meaning that
all messages will get passed to all objects.  It is intended
to be overridden if you want more complex behavior.  To
override with your own function, just do something like:
 
  def hell_no(p, m, t, object): return 0
  container.test = hell_no
test_limit_priority(self, priority, message, threshold, log_obj)
Only pass on messages with sufficient priority compared to
the master threshold.
 
  container = LogContainer([system, debug], threshold = 2)
  container.test = container.test_limit_priority
test_limit_threshold(self, priority, message, threshold, log_obj)
Only pass on messages to log objects whose threshold is
(numerically) lower than the master threshold.
 
  container = LogContainer([system, debug], threshold = 2)
  container.test = container.test_limit_threshold
write(self, priority, message=None)

 
class Logger
        USAGE:
      from logger import Logger
 
      log_obj = Logger(THRESHOLD)     # create the instance
 
      log_obj.log(3, 'message')       # log a message with priority 3
      log_obj(3, 'message')           # same thing
      log_obj(3, ['message'])         # same thing
 
      log_obj.test(3)                 # boolean - would a message of
                                      # this priority be printed?
 
      # a raw write call after the priority test, for writing arbitrary text
      log_obj.write(3, 'thing
to
write')  # (will not be followed by 
)
      
      pr = log_obj.gen_prefix(3)  # generate the prefix used for priority 3
 
      # see the examples in the test section for more
 
    ATTRIBUTES:
      (all of these are settable as keyword args to __init__)
 
      ATTRIBUTES   DEFAULT      DESCRIPTION
      ----------------------------------------------------------
      threshold    = 0          how verbose the program should be
      file_object  = sys.stderr file object to which output goes
      prefix       = ''         prefix string - repeated for more
                                important logs
      prefix_depth = 5          times prefix is repeated for logs
                                of priority 0.  Basically, set this
                                one larger than your highest log
                                priority.
      preprefix    = ''         string printed before the prefix
                                if callable, returned string will
                                be used (useful for printing time)
      postprefix   = ''         string printed after the prefix
      default      = 1          default priority to log at
 
  Methods defined here:
__call__ = log(self, priority, message=None)
__init__(self, threshold=0, file_object=<open file '<stderr>', mode 'w'>, prefix='', prefix_depth=5, preprefix='', postprefix='', default=1)
gen_prefix(self, priority)
Return the full prefix (including pre and post) for the
given priority.
 
If you use prefix and use a more complicated priority and
verbosity (non-numerical), then you should either give the
chosen object a __int__ method, or override this function.
log(self, priority, message=None)
Print a log message.  This prepends the prefix to each line
and does some basic formatting.
test(self, priority)
Return true if a log of the given priority would be printed.
 
This can be overridden to do any test you like.  Specifically,
log and threshold need not be integers.  They be arbitrary
objects.  You need only override this method, possibly
gen_prefix.
write(self, priority, message=None)
Print a log message.  In this case, 'message' must be a string
as it will be passed directly to the file object's write method.

 
Data
        AUTHOR = 'Michael D. Stenner <mstenner@phy.duke.edu>'
DATE = '2002/06/07'
VERSION = '0.4'