callgraph 1.0.0
This package defines decorators and IPython magic to display a dynamic call graph.
Requires Python: >=3.5

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