Package pythonutils :: Module standout
[hide private]
[frames] | no frames]

Module standout
source code

StandOut - the Flexible Output Object (FOO !) Adds optional logging to a file and setting of verbosity levels to the stdout stream This means that, for the most part, standard print statments can be used throughout your program and StandOut handles the rest.

Your user can choose a 'verbosity' level (how much information they want to receive), you give your messages a priority level, and only messages with a high enough priority are actually displayed.

A simple way of implementing varying degrees of verbosity. Additionally the output can be captured to a log file with no extra work. (simply pass in a filename when you craete the object and anything printed is sent to the file as well)

StandOut can now be used with sys.stderr as well as sys.stdout. This includes logging both sys.stdout and sys.stderr to the same file. See the sys.stderr section at the bottom of this.

SIMPLE USAGE (also see the tests which illustrate usage).

stout = StandOut(verbosity=verbositylevel)

or to log to a file : stout = StandOut(filename='log.txt')

The verbosity level can be changed at any time by setting stout.verbosity : stout.verbosity = 6

The priority of messages defaults to 5. This can be changed by setting stout.priority = 6 or print '&priority-6;'

The priority of an individual line can be set by starting the line with a priority marker : print '&priority-6;This text has a priority 6.' or by using the stout.write() method with a priority value: stout.write('This text has a priority 6. ', 6) (notice you must add the ' ' when using the stout.write method.)

Only messages with a priority equal to or greater than the current verbosity level will be printed. e.g. if stout.verbosity = 6 (or the stout object was created using stout=StandOut(verbosity=6) ) Only messages with a priority of 6 or above will be printed.

stout.write('This won't get printed , 5) print '&priority-4;Nor will this' stout.write('But this will ', 6) print '&priority-7;And so will this'

If for any reason you want to actually print a '&priority-n' marker at the start of a line then you can escape it with a '&priority-e;' : print '&priority-e;&priority-1;' will actually print : &priority-1;

StandOut will log to a file as well. Set this by passing in a filename=filename keyword when you create the object or by setting stout.filename at any time. The file has it's own priority, stout.file_verbosity. Again this can be set when the object is created and/or changed at any time. See the full docs below.

This means your user can set a verbosity level (at the command line probably), you give each message a priority setting and just use normal print statements in your program. Only messages above your user's setting are actually displayed. You can also set the log file to have a different priority threshhold to what is printed to the screen. (So either less or more is logged to the file than is displayed at runtime.)

You can also pass in another function which can be used to display messages with (e.g. to a GUI window or whatever). It also has it's own priority setting.

Any output method can be silenced by setting it to 0 All output can be silenced by setting the priority to 0

The stdout stream can be restored and any log file closed by calling stout.close()

verbosity = 1 is the highest verbosity = 9 is the lowest (only messages of priority 9 are printed) verbosity = 0 is special - it switches off printing altogether

LIST OF KEYWORDS AND METHODS

StandOut Possible keyword arguments (with defaults shown) are : (The following keywords also map to attributes of the StandOut object which can be read or set) priority = 5 verbosity = 5 filename = None file_verbosity = 5 file_mode = 'w' print_fun = None printfun_verbosity = 5

Keyword arguments should either be passed in as a dictionary or as keywords when the object is created. If a dictionary is passed in, any other keywords will be ignored. Any missing keywords will use the defaults.

Methods ( stout = StandOut() ): stout.close() stout.write(line, priority) stout.set_print(function) stout.setall(verbosity)

the original stdout can be reached using : stout.output.write()

NOTE normal print statements make two calls to stdout.write(). Once for the text you are printing and another for the trailing ' ' or ' '. StandOut captures this to make sure the trailing ' ' or ' ' is printed at the same priority as the original line. This means you shouldn't use stout.write(line) where line uses the '&priority-n;' markers. (Because stout.write(line) only makes one call, not two). Either call stout.write(line, priority) to set a priority for that line. or set stout.priority directly.

EXPLANATION OF KEYWORDS AND METHODS

priority = 5 This sets the priority for messages. If priority is 5 - then only output methods with a 'verbosity' of 5 or lower will display them. This value can later be set by adjusting the stout.priority attribute or using the priority markers.

verbosity = 5 This is the verbosity level for messages to be printed to the screen. If the verbosity is 5 then only messages with a priority of 5 or higher will be sent to the screen. (Like a normal print statement). You can nadjust this at stout.verbosity

filename = None If you pass in a filename when you create the object it will be used as a logfile. It has it's own 'verbosity' level called 'file_verbosity'. If you don't pass in a filename, you can later add one by setting stout.filename Changing stout.filename after you have already set one is a bad thing to do :-)

file_verbosity = 5 This is the verbosity level of the log file. Only messages with a priority higher than this will be sent to the logfile.

print_fun = None If you pass in a function (that takes one parameter - the line to be printed) this will be used to print as well. The function isn't stored at stout.print_fun - this value is just set to True to say we have a function. This could be used for displaying to the output window of a GUI, for example. If you want to pass in a function after obect creation then use the stout.set_print(function) method. You musn't have print statements in your function or you will get stuck in a loop (call stout.output.write(line) instead)

printfun_verbosity = 5 Any function you pass in also has it's own verbosity setting - printfun_verbosity.

stream = 'output' By default StandOut will divert the sys.stdout stream. Set to 'error' to divert the sys.stderr

share = False You can divert both sys.stdout and sys.stderr. You can log both to the same file. Set a filename for your sys.stdout object and set share = True for your sys.stderr object. Any lines sent to sys.stderr will have a prefix attached to them. See 'error_marker'

error_marker = '[err] ' This is the marker put before every line logged from sys.stderr. It only applies if share is on - this means both streams are logged to the same file.

stout.close() When your program has finished with the obejct it should call stout.close() which restores sy.stdout and closes any logfile we have been using.

stout.write(line, priority) This can be used as an alternative way of specifying a priority for an individual line. It leaves stout.priority unaffected. Any calls to stout.write must have ' ' at the end if you want it to end with a newline. If you don't specify a priority then it behaves like sys.stdout.write would. Don't use priority markers with this and method and you can't use priority = 0 (the priority setting will be ignored)

stout.set_print(function) This is used to pass in an additional printing function after the object has been created.

stout.setall(verbosity) Thisis a quick way of changing the verbosity for all three output methods.

Setting verbosity, file_verbosity or printfun_verbosity to 0 disables that ouput method. Setting priority to 0 switches off all output.

If you want to print to stdout directly and bypass the stout object for any reason - it is saved at stout.output Calls to stout.output.write(line) have the same effect that sys.stdout.write(line) would have had.

PRIORITY MARKERS

As well as directly setting stout.priority and using stout.write(line, priority) You can set the priority of a individual line or change the general priority setting just using print statements. This is using 'priority markers'.

print '&priority-n;' # sets the priority to n, where n is 0-9 print '&priority-n;The stuff to print' # sets the priority of just that line to n

If you actually want to print '&priority-n;' at the start of a line then you should escape it by putting '&priority-e;' in front of it. '&priority-e;' can also be escaped in the same way !

Don't use priority markers if you are making direct calls to stout.write() use stout.write(line, priority) to set the priority of an individual line or alter stout.priority to adjust the general priority.

sys.stderr

StandOut can now be used to divert sys.stderr as well as sys.stdout. To create an output object that does for sys.stderr exactly the same as we would do for sys.stdout use : stout2 = StandOut(stream='error')

It can log to a file and has all the properties that we had for sys.stdout. If you wanted to log to the same file as you are using for sys.stdout you can't just pass it the same filename. The two objects would both try to have a write lock on the same file.

What you do is pass the 'share' keyword to the error object when you create it :

stout = StandOut(filename='log.txt') stout2 = StandOut(stream='error', share=True)

Anything sent to sys.stdout or sys.stderr will now be logged in the 'log.txt' file. Every line sent to sys.stderr will be prefixed with '[err] ' which is the default error marker. You can adjust this with the 'error_marker' keyword.

stout2 = StandOut(stream='error', share=True, error_marker='ERROR ')



Classes [hide private]
StandOut  

Functions [hide private]
  afunction(line)

Variables [hide private]
test  
test2  

Imports: sys

Function Details [hide private]

afunction(line)

source code 

Variables Details [hide private]

test

Value:
StandOut()                                                             
      

test2

Value:
StandOut(stream='error',share=True)