sanka

a function decorator for surfacing dead code

Quick start

The "examples/" directory is home to sanka use cases.

examples/
├── actionpack/
│   ├── example.py
│   └── requirements.txt
└── ...

A docker image capable of running an example can be built using a nox command:

EXAMPLE=actionpack nox -s image

where the example referenced in the image can be specified using the "EXAMPLE" environment variable. To run a container, execute something like the following:

docker run -e RUN_DURATION_SECONDS=10 -e CALL_DELAY_SECONDS=5 sanka:0.3.0

Setup

Ensure nox is installed.

pip install nox

Run nox to install sanka and run tests.

Usage

the basics

Decorate any funciton with @sanka.

@sanka
def function():
    pass

The decorator instance tracks function calls so the call count can be gotten as follows:

function(YaDead)  #=> returns number of times `function` was called

callbacks

One can also pass a callback argument to the @sanka decorator:

from string import Template

report = Template('Called $f called $this_many times')

callback: Callable[[int], None] = lambda tally: print(
    "Ya, mon."
    if tally == 0
    else report.substitute(f=str(function), this_many=tally)
)

@sanka(callback=callback)
def function():
    pass

The callback is expected to be a single-parameter function that accepts an int. This int is the latest tally for the number of times the decorated function has been called. To access the call count for the docorated function, just ask @sanka if it's "dead":

function(YaDead)

and as per the example you'd get this response if the function had never been called:

Ya, mon.

callback control

By default, callbacks are only executed when YaDead is passed. The callback can be executed on every function call if desired.

@sanka(callback=callback, only_callback_when_dead=False)
def function():
    pass

Now, every time function is called, the callback will also be called.