Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/osteele/callgraph

Magic to display dynamic call graphs of Python function calls
https://github.com/osteele/callgraph

education ipython-magic jupyter-notebook-extension python visualizations

Last synced: about 2 months ago
JSON representation

Magic to display dynamic call graphs of Python function calls

Awesome Lists containing this project

README 

        
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