Callgraph Magic

|PyPI version| |Doc Status| |License| |Supported Python|

Callgraph is a Python package that defines a decorator, and Jupyter magic, to draw dynamic call graphs_ of Python function calls.

It’s intended for classroom use, but may also be useful for self-guided exploration.

The package defines a Jupyter IPython_ magic_, %callgraph, that displays a call graph within a Jupyter cell:

.. code:: python

from functools import lru_cache

@lru_cache()
def lev(a, b):
    if "" in (a, b):
        return len(a) + len(b)

    candidates = []
    if a[0] == b[0]:
        candidates.append(lev(a[1:], b[1:]))
    else:
        candidates.append(lev(a[1:], b[1:]) + 1)
    candidates.append(lev(a, b[1:]) + 1)
    candidates.append(lev(a[1:], b) + 1)
    return min(candidates)

%callgraph -w10 lev("big", "dog"); lev("dig", "dog")

|image0|

It also provides a Python decorator, callgraph.decorator, that instruments a function to collect call graph information and render the result.

Jupyter / IPython Usage

.. code:: bash

$ pip install callgraph

In a Jupyter IPython notebook:

.. code:: python

%load_ext callgraph

def nchoosek(n, k):
    if k == 0:
        return 1
    if n == k:
        return 1
    return nchoosek(n - 1, k - 1) + nchoosek(n - 1, k)

%callgraph nchoosek(4, 2)

As an alternative to including %load_ext callgraph in each notebook that uses %callgraph, you can add the extension to the Notebook configuration file in your IPython profile.

Your configuration file is probably called ~/.ipython/profile_default/ipython_config.py. (You can run ipython profile locate to find it.) Edit this file to include the following line::

c.InteractiveShellApp.extensions = ["callgraph.extension"]

(If your configuration file already includes an uncommented statement c.InteractiveShellApp.extensions = […], edit the list of extensions in that line to include "callgraph.extension".

See extension example notebook_ for additional examples.

Decorator Usage

.. code:: bash

$ pip install callgraph

.. code:: python

from functools import lru_cache
import callgraph.decorator as callgraph

@callgraph()
@lru_cache()
def nchoosek(n, k):
    if k == 0:
        return 1
    if n == k:
        return 1
    return nchoosek(n - 1, k - 1) + nchoosek(n - 1, k)

nchoosek(5, 2)

nchoosek.__callgraph__.view()

See the API documentation_ for additional documentation.

See the decorator example notebook_ for additional instructions and examples.

Development

Install dev tools, and set up a Jupyter kernel for the current python enviromnent:

.. code:: bash

$ pip install -r requirements-dev.txt
$ python -m ipykernel install --user

Install locally:

.. code:: bash

flit install --symlink

Acknowledgements

Callgraph uses the Python graphviz package. Python graphviz uses the Graphviz package.

License

MIT

.. |PyPI version| image:: https://img.shields.io/pypi/v/callgraph.svg :target: https://pypi.python.org/pypi/callgraph :alt: Latest PyPI Version .. |Doc Status| image:: https://readthedocs.org/projects/callgraph/badge/?version=latest :target: http://callgraph.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status .. |License| image:: https://img.shields.io/pypi/l/callgraph.svg :target: https://pypi.python.org/pypi/callgraph :alt: License .. |Supported Python| image:: https://img.shields.io/pypi/pyversions/callgraph.svg :target: https://pypi.python.org/pypi/callgraph :alt: Supported Python Versions

.. _dynamic call graphs: https://en.wikipedia.org/wiki/Call_graph .. _IPython: https://ipython.org .. _magic: http://ipython.readthedocs.io/en/stable/interactive/magics.html .. _graphviz package: https://github.com/xflr6/graphviz .. _Graphviz: https://www.graphviz.org

.. |image0| image:: ./docs/images/lev.svg .. _API documentation: http://callgraph.readthedocs.io/en/latest/?badge=latest#module-callgraph .. _extension example notebook: https://github.com/osteele/callgraph/blob/master/examples/callgraph-magic-examples.ipynb .. _decorator example notebook: https://github.com/osteele/callgraph/blob/master/examples/callgraph-decorator-examples.ipynb