breadcrumbs: keep track of what is going on

This library started with a rather simple objective in mind: keep track of a sequence of transforming steps.

It is extremely easy to use:

>>> import breadcrumbs as bc
>>> crumb = bc.Crumb("start")
>>> crumb.info.update(value=35)
>>> crumb.info.update(other_value=70)
>>> print(crumb.info)
{'value': 35, 'other_value': 70}

A Crumb can has three attributes: a name (here Start), and two dicts (info and extra) to store additional information. You can also store dependent crumbs using the put_crumb method.

'What is the big deal?' you might ask, 'You are just writing a dict!' True, but the cool thing is that it works a little bit like logging and therefore you use it decoupled across you code:

>>> def func1():
...     bc.info.update(value=35)
>>> def func2():
...     bc.extra.update(other_value=70)
>>> crumb = bc.Crumb("start")
>>> with bc.context(crumb):
...     func2()
...     func1()
>>> print(crumb.info)
{'value': 35}
>>> print(crumb.extra)
{'other_value': 70}

func1 and func2 now nothing about crumb but it just works.

You can also decorate a function to do some things for you automatically.

>>> @bc.aware()
... def func1(x, y):
...     return x + y
>>> crumb = bc.Crumb("start")
>>> with bc.context(crumb):
...     func1(1, 2)
>>> print(crumb.trail)
(Crumb('func1', info={'x': 1, y: '2'}, extra={}))

So in trail you can see that func1 has been called with certain parameters. You can redact some parameters that might be memory intensive or pointless to store.

>>> @bc.aware(redact_params='y')
... def func1(x, y):
...     return x + y
>>> crumb = bc.Crumb("start")
>>> with bc.context(crumb):
...     func1(1, 2)
>>> print(crumb.trail)
(Crumb('func1', info={'x': 1}, extra={}))

To redact more parameters, just pass an iterable.

A useful feature is that a TrailMixin allows you to add object specific notes and teach this to functions.

>>> class MyCoolClass(bc.TrailMixin):
...     # Here goes your cool class
...     internal = 10
>>> @bc.aware(trail_param="obj")
... def func1(obj, x, y):
...     return (x + y) * obj.internal
>>> myobj = MyCoolClass()
>>> func1(myobj, 1, 2)
>>> print(myobj.trail)
(Crumb('func1', info={'x': 1, 'y': 2}, extra={}))

Quick Installation

To install breadcrumbs, simply:

$ pip install use-breadcrumbs

and then simply enjoy it!

It runs in Python 3.7+ with no other dependency. It is licensed under BSD.

breadcrumbs is maintained by a community. See AUTHORS for a complete list.

To review an ordered list of notable changes for each version of a project, see CHANGES