;ò µAc@s%dZdkZdkZdZdZdZdZdfd„ƒYZdfd „ƒYZe d jo¾d Z d e GHee d dƒZ dGHx(e ddƒD]Z e e de ƒq™WdGHdkZd„Zee _dGHx(e ddƒD]Z e e de ƒqéWdGHdGHee dd dƒZee egddƒZeie_dGHx(e ddƒD]Z ee de ƒq]WdGHdZdGHe eƒd GHe ed!ƒd"GHe ed#ƒd$GHe d!ƒd%GHe ied!ƒd&GHe d'hd(d)<ƒd*GHee _e d+ƒe id+ƒndS(,s 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. If it is None, then the logs are quietly dropped. 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. :) Ns*Michael D. Stenner s0.6s 2002/08/13s4http://www.dulug.duke.edu/~mstenner/software/logger/sLoggercBshtZdZdeidddddd„Zd„Zd„Zed„Z e Z ed „Z d „Z RS( sÛA class for file-object logging 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 -- (this will not be followed by \n) log_obj.write(3, 'thing\nto\nwrite') # generate the prefix used for priority 3 pr = log_obj.gen_prefix(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 isiicCsC||_||_||_||_||_||_||_dS(N(s thresholdsselfs file_objectsprefixs prefix_depths preprefixs postprefixsdefault(sselfs thresholds file_objectsprefixs prefix_depths preprefixs postprefixsdefault((s/usr/share/yum/logger.pys__init__Çs      cCst|iƒt|ƒjSdS(s4 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. N(sintsselfs thresholdspriority(sselfspriority((s/usr/share/yum/logger.pystest×s cCs—t|iƒo|iƒ}n |i}|ioU|it|ƒ}|djo d}nx(td|ƒD]}||i}qmWn||i SdS(s* 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. iiN( scallablesselfs preprefixsprefixs prefix_depthsintsprioritysdepthsrangesis postprefix(sselfsprioritysprefixsisdepth((s/usr/share/yum/logger.pys gen_prefixäs    cCs |i||ƒ\}}|i|ƒoÝ|itjodSnt |ƒt dƒjo2t i |dƒ}|ddjo |d=qÉn?t |ƒt gƒjot t i|ƒ}nt|ƒg}|i|ƒ}x*|D]}|ii||dƒqßWndS(su Print a log message. This prepends the prefix to each line and does some basic formatting. Nss iÿÿÿÿ(sselfs _use_defaultsprioritysmessagespsmstests file_objectsNonestypesstringssplitsmlistsmapsrstripsstrs gen_prefixsprefixslineswrite(sselfsprioritysmessagesmlistsmspsprefixsline((s/usr/share/yum/logger.pyslogús cCsX|i||ƒ\}}|i|ƒo,|itjodSn|ii |ƒndS(s™ 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. N( sselfs _use_defaultsprioritysmessagespsmstests file_objectsNoneswrite(sselfsprioritysmessagesmsp((s/usr/share/yum/logger.pyswrites cCs,|tjo|i|fSn ||fSdS(s0Substitute default priority if none was providedN(smessagesNonesselfsdefaultspriority(sselfsprioritysmessage((s/usr/share/yum/logger.pys _use_defaults ( s__name__s __module__s__doc__ssyssstderrs__init__stests gen_prefixsNoneslogs__call__swrites _use_default(((s/usr/share/yum/logger.pysLoggeršs +!   s LogContainercBsktZdZgedd„Zd„Zed„ZeZed„Zd„Z d„Z d„Z d „Z RS( sAA class for consolidating calls to multiple Logger objects USAGE: from logger import Logger, LogContainer log_1 = Logger(threshold=1, file_object=sys.stdout) log_2 = Logger(threshold=2, preprefix='LOG2') log = LogContainer([log_1, log_2]) log(1, 'message') # printed by log_1 and log_2 log(2, 'message') # only printed by log_2 ATTRIBUTES: (all of these are settable as keyword args to __init__) ATTRIBUTES DEFAULT DESCRIPTION ---------------------------------------------------------- list = [] list of Logger objects threshold = None meaning depends on test - by default threshold has no effect default = 1 default priority to log at icCs||_||_||_dS(N(slistsselfs thresholdsdefault(sselfslists thresholdsdefault((s/usr/share/yum/logger.pys__init__:s  cCs|ii|ƒdS(s"Add a log object to the container.N(sselfslistsappendslog_obj(sselfslog_obj((s/usr/share/yum/logger.pysadd?scCs`|i||ƒ\}}xA|iD]6}|i|||i |ƒo|i ||ƒq"q"WdS(s_Log a message to all contained log objects, depending on the results of test() N( sselfs _use_defaultsprioritysmessagespsmslistslog_objstests thresholdslog(sselfsprioritysmessageslog_objsmsp((s/usr/share/yum/logger.pyslogCs  cCs`|i||ƒ\}}xA|iD]6}|i|||i |ƒo|i ||ƒq"q"WdS(N( sselfs _use_defaultsprioritysmessagespsmslistslog_objstests thresholdswrite(sselfsprioritysmessageslog_objsmsp((s/usr/share/yum/logger.pyswriteNs  cCs,|tjo|i|fSn ||fSdS(s0Substitute default priority if none was providedN(smessagesNonesselfsdefaultspriority(sselfsprioritysmessage((s/usr/share/yum/logger.pys _use_defaultTs cCsdSdS(sUTest 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 iN((sselfsprioritysmessages thresholdslog_obj((s/usr/share/yum/logger.pystestYscCs||jSdS(sÞOnly pass on messages with sufficient priority compared to the master threshold. container = LogContainer([system, debug], threshold = 2) container.test = container.test_limit_priority N(sprioritys threshold(sselfsprioritysmessages thresholdslog_obj((s/usr/share/yum/logger.pystest_limit_priorityjscCs|i|jSdS(sõ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 N(slog_objs threshold(sselfsprioritysmessages thresholdslog_obj((s/usr/share/yum/logger.pystest_limit_thresholdss( s__name__s __module__s__doc__sNones__init__saddslogs__call__swrites _use_defaultsteststest_limit_prioritystest_limit_threshold(((s/usr/share/yum/logger.pys LogContainers       s__main__isTHRESHOLD = %ss preprefixsTEST s Lets log a few things!iþÿÿÿi slog priority %ss, Now make it print the time for each log...cCs#tidtitiƒƒƒSdS(Ns%m/%d/%y %H:%M:%S (stimesstrftimes localtime(((s/usr/share/yum/logger.pys printtimeˆss and log a few more thingss< now create another with a different prefix and priority...s and put them in a container...isLOG2 s thresholdis and log a bit mores: OK, enough of the container... lets play with formattingsabcd efgh ijkls no trailing newlines with trailing newlines s two trailing newliness s log JUST a newlines/ use the write method, with a trailing newlines print some complex objectiskeysvalues= now set the file object to None (nothing should be printed)sTHIS SHOULD NOT BE PRINTED(s__doc__ssyssstringsAUTHORsVERSIONsDATEsURLsLoggers LogContainers__name__s thresholdslogsrangesistimes printtimes preprefixslog2scontstest_limit_prioritystestsstuffswritesNones file_object(s printtimeslog2sstringsAUTHORsURLsiscontstimesstuffssyss thresholdsVERSIONs LogContainersDATEsLoggerslog((s/usr/share/yum/logger.pys?sf  …]