Logs program flow with decorators
Project description
What is stump?
Stump:
n. the lower end of a tree or plant left after the main part is removed
Log:
n. a portion or length of the trunk or of a large limb of a felled tree
stump
is a logging utility for Python that uses the standard
logging module under the covers. However, a stump is a different part of a
tree than a log and as such should be utilized differently. stump
offers various method decorators that really cover all the bases of logging
for debugging. stump
’s method decorators are flexible and concise, act
as additional documentation, don’t clutter the main code of the method body and
accept a natural format string that is easy to form and read.
Installation
Install from pip
pip install stump
Alternatively, clone this repo and install from your local copy
git clone https://github.com/EricCrosson/stump
cd stump
python setup.py install
Usage
Once installed simply import stump
and pass a logger to
stump.configure
, as demonstrated in the Examples section.
The different stump
decorators all inherit the same functionality,
with minor behavioral differences. Each decorator accepts a logging string as
the first argument. This string may contain the values of the decorated method’s
parameters. For example, to log the values of parameters passed to
accelerate
the following format string could be used
@stump.put('Object is {weight} lbs with {gravity} m/s^2 acceleration')
def accelerate(weight, gravity):
work()
If invoked by accelerate(42, 9.8)
the logs generated would be
INFO:accelerate:Object is 42 lbs with 9.8 m/s^2 acceleration...
INFO:accelerate:Object is 42 lbs with 9.8 m/s^2 acceleration...done
API
The standard decorator, stump.put
, prints a message upon entering and
exiting a method. The below table describes the public api exposed by stump
.
stump.put
Print a message upon entering and exiting the method
stump.pre
Print a message only upon entering the method
stump.post
Print a message only upon exiting the method
stump.date
Like
stump.put
, but include a date- and time- stampstump.ret
Like
stump.put
, but include the method’s return value
Examples
Import the stump
library and configure the stump
logger
#!/usr/bin/env python
import stump
# configure a logger for stump
import sys
import logging
logging.basicConfig(stream=sys.stdout, level=logging.DEBUG)
logger = logging.getLogger()
stump.configure(logger)
And decorate some methods. stump
allows you to interpolate a string
representation of the parameter values to decorated methods by simply
wrapping the parameter name in curly braces.
@stump.post('Using nitrous')
def use_nitrous():
raise NoNitrousException('You never installed nitrous!')
@stump.ret('"Calculating" boost for car {car}')
def car_boost(car):
try:
use_nitrous()
except:
return random.random() * 100
@stump.pre()
def ready():
light = 'red'
@stump.pre()
def set():
light = 'yellow'
@stump.post()
def go():
light = 'green'
@stump.date('Racing {car}', print_return=True)
def race(car):
luck = car_boost(car)
return random.randint(1, round(luck))
ready()
set()
go()
race('wacky')
This example logs the following events
INFO:root:ready...
INFO:root:set...
INFO:root:go...done
INFO:root:race:2016-02-14 23:33:37:Racing wacky...
INFO:root:car_boost:"Calculating" boost for car wacky...
INFO:root:use_nitrous:Using nitrous...
INFO:root:use_nitrous:Using nitrous...threw exception NoNitrousException with message You never installed nitrous!
INFO:root:car_boost:"Calculating" boost for car wacky...done (returning 56.138089977332776)
INFO:root:race:2016-02-14 23:33:37:Racing wacky...done (returning 2)
License
This code is released under the MIT license.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.