========
calltree
========

.. toctree::
   :hidden:



.. index:: calltree
.. module:: calltree
   :noindex:

Support to build a simple call-tree for Python code.

This uses Python's built-in introspection to determine which functions/methods
a given function/method appears to invoke. The process is performed recursively
in order to form a tree of possible calls. The algorithm is deliberately
limited.

- Only reachability is of interest, no attempt to represent any levels of
  recursion is implemented. THIS IS NOT REALLY TRUE!
- Conditional code is not handled at all!


Module Members
==============

| :class:`~FunctionInfoCache`
| :class:`~RunTracer`
| :class:`~Step`
| :class:`~TracedFunction`


Classes
-------


.. class:: FunctionInfoCache()

   An in-memory cache used to store information about 'interesting'
   functions.


   .. method:: getFuncInfo(obj)
      :noindex:

      Get information about a an object, if it is a function.

      If the object is not a function ``None`` is returned. If the function
      is cached then the information is retrieved from the cache. Otherwise
      a new `TracedFunction` is created and added to the cache.


      **Return Value**

        If the obj argument is not a function then ``None``. Otherwise a
        `TracedFunction`  instance.


      **Arguments**

        *obj*
          The object to inspect.

   .. method:: getFuncInfoByName(module, name)
      :noindex:

      Get information about a function with a given name.

      Like :meth:`getFuncInfo`, this will use cached information if possible.


      **Return Value**

        If the name does not identify a function then ``None``. Otherwise a
        `TracedFunction` instance.


      **Arguments**

        *module*
          This should typically be a Python module instance, but it can
          be anything that 'looks' like a module.

        *name*
          The name of the function.

   .. method:: getFunctionFromCode(func_code)
      :noindex:

      Get function info for a code object.


   .. method:: getMethodInfoByName(klass, name)
      :noindex:

      Get information about a method with a given name.

      This is analagous to :meth:`getFuncInfoByName`, but for methods in a class.


.. class:: TracedFunction()

   Mapping of a test function (direct or indirect) to useful information.


.. index::
   func; cstest.calltree.TracedFunction

.. attribute:: func
   :noindex:

   The function in question.


.. index::
   startLine; cstest.calltree.TracedFunction

.. attribute:: startLine
   :noindex:

   The number of the line where the function's definition begins.


.. property:: inlined
   :noindex:

   True if the function has been decorated marked with `cs_inline`.


.. property:: invocations
   :noindex:

   Ordered points of interests that are function/method invocations.


.. property:: steps
   :noindex:

   Ordered points of interest that are test steps.


   .. method:: getStep(lNum)
      :noindex:

      Get the step above the code for a given line number.


      **Return Value**

        If the line of code is preceded by a step comment then the `Step`
        instnce. Otherwise ``None`` is returned.


      **Arguments**

        *lNum*
          The line number of the code.

   .. method:: init(func, cache)
      :noindex:

      Find all test steps and function invocations for this function.

      This is not intended to be used outside this module. It exists because
      a TracedFunction needs to be created before the function details can be
      added.


   .. method:: walkSteps(level=0)
      :noindex:

      Generator: Walk all the steps for this function and those it invokes.

      This yields tuples of ``level, func, (lnum, step)``. The ``lnum`` is
      the line number within the source file. The ``step`` is a `Step`
      instance. The ``level`` is the level of step nesting and is zero based.


.. class:: Step(lines)

   Information about a step in a test.

   This is used to store the lines that describe a test step, as extraced from
   a comment in a function or method.


.. class:: RunTracer(funcCache, stepCB)

   Context manager that uses sys.settrace to identify steps as they occur.

   This can be used when tests execute in order to provide a running
   commentary of the tests's progress.


   **Arguments**

     funcCache
       Should be a `FunctionInfoCache` or equivalent object.

     stepCB
       A function to be called as each step is detected. It is invoked as
       ``stepCB(level, nStr, step)``. The ``level`` is a number indicating
       how deeply nested the current step is. The ``nStr`` indicates the
       step's number. It is a dotted number, which has ``level`` + 1
       parts. The ``step`` is a `Step` instance.


   .. method:: trace(frame, event, arg)
      :noindex:

      Standard trace functions.

      TODO:Add detail.