exdoc module

This module can be used to automatically generate exceptions documentation marked up in reStructuredText with help from cog and the putil.exh module.

The exceptions to auto-document need to be “traced” before the documentation is generated; in general tracing consists of calling the methods, functions and/or class properties so that all the required putil.exh.ExHandle.addex() (or putil.exh.ExHandle.addai()) calls are covered (exceptions generated by contracts defined using the putil.pcontracts module are automatically traced when the contracts are checked). A convenient way of tracing a module is to simply run its test suite, provided that it covers the exceptions that need to be documented.

For example, it is desired to auto-document the exceptions of a module my_module.py, which has tests in test_my_module.py. Then a tracing module trace_my_module.py can be created to leverage the already written tests:

# trace_my_module_1.py
# Option 1: use already written test bench
from __future__ import print_function
import copy, os, pytest, putil.exdoc

def trace_module(no_print=True):
    """ Trace my_module exceptions """
    pwd = os.path.dirname(__file__)
    script_name = repr(os.path.join(pwd, 'test_my_module.py'))
    with putil.exdoc.ExDocCxt() as exdoc_obj:
        if pytest.main('-s -vv -x {0}'.format(script_name)):
            raise RuntimeError(
                'Tracing did not complete successfully'
            )
    if not no_print:
        module_prefix = 'docs.support.my_module.'
        callable_names = ['func', 'MyClass.value']
        for callable_name in callable_names:
            callable_name = module_prefix+callable_name
            print('\nCallable: {0}'.format(callable_name))
            print(exdoc_obj.get_sphinx_doc(callable_name, width=70))
            print('\n')
    return copy.copy(exdoc_obj)

if __name__ == '__main__':
    trace_module(False)

The context manager putil.exdoc.ExDocCxt sets up the tracing environment and returns a putil.exdoc.ExDoc object that can the be used in the documentation string of each callable to extract the exceptions documentation. In this example it is assumed that the tests are written using pytest, but any test framework can be used. Another way to trace the module is to simply call all the functions, methods or class properties that need to be documented. For example:

# trace_my_module_2.py
# Option 2: manually use all callables to document
from __future__ import print_function
import copy, putil.exdoc, docs.support.my_module

def trace_module(no_print=True):
    """ Trace my_module_original exceptions """
    with putil.exdoc.ExDocCxt() as exdoc_obj:
        try:
            docs.support.my_module.func('John')
            obj = docs.support.my_module.MyClass()
            obj.value = 5
            obj.value
        except:
            raise RuntimeError(
                'Tracing did not complete successfully'
            )
    if not no_print:
        module_prefix = 'docs.support.my_module.'
        callable_names = ['func', 'MyClass.value']
        for callable_name in callable_names:
            callable_name = module_prefix+callable_name
            print('\nCallable: {0}'.format(callable_name))
            print(exdoc_obj.get_sphinx_doc(callable_name, width=70))
            print('\n')
    return copy.copy(exdoc_obj)

if __name__ == '__main__':
    trace_module(False)

And the actual module my_module code is (before auto-documentation):

# my_module.py
# Exception tracing initialization code
"""
[[[cog
import os, sys
sys.path.append(os.environ['TRACER_DIR'])
import trace_my_module_1
exobj = trace_my_module_1.trace_module(no_print=True)
]]]
[[[end]]]
"""

import putil.exh

def func(name):
    r"""
    Prints your name

    :param   name: Name to print
    :type name: string

    .. [[[cog cog.out(exobj.get_sphinx_autodoc(width=69))]]]
    .. [[[end]]]

    """
    # Raise condition evaluated in same call as exception addition
    putil.exh.addex(
        TypeError, 'Argument `name` is not valid', not isinstance(name, str)
    )
    return 'My name is {0}'.format(name)

class MyClass(object):
    """ Stores a value """
    def __init__(self, value=None):
        self._value = None if not value else value

    def _get_value(self):
        # Raise condition not evaluated in same call as
        # exception additions
        exobj = putil.exh.addex(RuntimeError, 'Attribute `value` not set')
        exobj(not self._value)
        return self._value

    def _set_value(self, value):
        exobj = putil.exh.addex(RuntimeError, 'Argument `value` is not valid')
        exobj(not isinstance(value, int))
        self._value = value

    value = property(_get_value, _set_value)
    r"""
    Sets or returns a value

    :type:  integer
    :rtype: integer or None

    .. [[[cog cog.out(exobj.get_sphinx_autodoc(width=69))]]]
    .. [[[end]]]
    """

A simple shell script can be written to automate the cogging of the my_module.py file:

#!/bin/bash
set -e

finish() {
    export TRACER_DIR=""
    cd ${cpwd}
}
trap finish EXIT

input_file=${1:-my_module.py}
output_file=${2:-my_module.py}
export TRACER_DIR=$(dirname ${input_file})
cog.py -e -x -o ${input_file}.tmp ${input_file} > /dev/null && \
    mv -f ${input_file}.tmp ${input_file}
cog.py -e -o ${input_file}.tmp ${input_file} > /dev/null && \
    mv -f ${input_file}.tmp ${output_file}

After the script is run and the auto-documentation generated, each callable has a reStructuredText marked-up :raises: section:

# my_module_ref.py
# Exception tracing initialization code
"""
[[[cog
import os, sys
sys.path.append(os.environ['TRACER_DIR'])
import trace_my_module_1
exobj = trace_my_module_1.trace_module(no_print=True)
]]]
[[[end]]]
"""

import putil.exh

def func(name):
    r"""
    Prints your name

    :param   name: Name to print
    :type name: string

    .. [[[cog cog.out(exobj.get_sphinx_autodoc(width=69))]]]
    .. Auto-generated exceptions documentation for
    .. docs.support.my_module.func

    :raises: TypeError (Argument \`name\` is not valid)

    .. [[[end]]]

    """
    # Raise condition evaluated in same call as exception addition
    putil.exh.addex(
        TypeError, 'Argument `name` is not valid', not isinstance(name, str)
    )
    return 'My name is {0}'.format(name)

class MyClass(object):
    """ Stores a value """
    def __init__(self, value=None):
        self._value = None if not value else value

    def _get_value(self):
        # Raise condition not evaluated in same call as
        # exception additions
        exobj = putil.exh.addex(RuntimeError, 'Attribute `value` not set')
        exobj(not self._value)
        return self._value

    def _set_value(self, value):
        exobj = putil.exh.addex(RuntimeError, 'Argument `value` is not valid')
        exobj(not isinstance(value, int))
        self._value = value

    value = property(_get_value, _set_value)
    r"""
    Sets or returns a value

    :type:  integer
    :rtype: integer or None

    .. [[[cog cog.out(exobj.get_sphinx_autodoc(width=69))]]]
    .. Auto-generated exceptions documentation for
    .. docs.support.my_module.MyClass.value

    :raises:
     * When assigned

       * RuntimeError (Argument \`value\` is not valid)

     * When retrieved

       * RuntimeError (Attribute \`value\` not set)

    .. [[[end]]]
    """

Warning

Due to the limited introspection capabilities of class properties, only properties defined using the property built-in function can be documented with putil.exdoc.ExDoc.get_sphinx_autodoc(). Properties defined by other methods can still be auto-documented with putil.exdoc.ExDoc.get_sphinx_doc() and explicitly providing the method/function name.

Context managers

class putil.exdoc.ExDocCxt(exclude=None, pickle_fname=None, in_callables_fname=None, out_callables_fname=None)

Bases: object

Context manager to simplify exception tracing; it sets up the tracing environment and returns a putil.exdoc.ExDoc object that can the be used in the documentation string of each callable to extract the exceptions documentation with either putil.exdoc.ExDoc.get_sphinx_doc() or putil.exdoc.ExDoc.get_sphinx_autodoc().

Parameters:
  • exclude (list of strings or None) – Module exclusion list. A particular callable in an otherwise fully qualified name is omitted if it belongs to a module in this list. If None all callables are included
  • pickle_fname (FileName or None) – File name to pickle traced exception handler (useful for debugging purposes). If None all pickle file is created
  • in_callables_fname (FileNameExists or None) – File name that contains traced modules information. File can be produced by either the putil.pinspect.Callables.save() or putil.exh.ExHandle.save_callables() methods
  • out_callables_fname (FileNameExists or None) – File name to save traced modules information to in JSON format. If the file exists it is overwritten
Raises:
  • OSError (File [in_callables_fname] could not be found)
  • RuntimeError (Argument `in_callables_fname` is not valid)
  • RuntimeError (Argument `exclude` is not valid)
  • RuntimeError (Argument `out_callables_fname` is not valid)
  • RuntimeError (Argument `pickle_fname` is not valid)

For example:

>>> from __future__ import print_function
>>> import putil.eng, putil.exdoc
>>> with putil.exdoc.ExDocCxt() as exdoc_obj:
...     value = putil.eng.peng(1e6, 3, False)
>>> print(exdoc_obj.get_sphinx_doc('putil.eng.peng'))
.. Auto-generated exceptions documentation for putil.eng.peng

:raises:
 * RuntimeError (Argument \`frac_length\` is not valid)

 * RuntimeError (Argument \`number\` is not valid)

 * RuntimeError (Argument \`rjust\` is not valid)

Classes

class putil.exdoc.ExDoc(exh_obj, depth=None, exclude=None)

Bases: object

Generates exception documentation with reStructuredText mark-up

Parameters:
  • exh_obj (putil.exh.ExHandle) – Exception handler containing exception information for the callable(s) to be documented
  • depth (non-negative integer or None) – Default hierarchy levels to include in the exceptions per callable (see putil.exdoc.ExDoc.depth). If None exceptions at all depths are included
  • exclude (list of strings or None) – Default list of (potentially partial) module and callable names to exclude from exceptions per callable (see putil.exdoc.ExDoc.exclude). If None all callables are included
Return type:

putil.exdoc.ExDoc
Raises:
  • RuntimeError (Argument `depth` is not valid)
  • RuntimeError (Argument `exclude` is not valid)
  • RuntimeError (Argument `exh_obj` is not valid)
  • RuntimeError (Exceptions database is empty)
  • RuntimeError (Exceptions do not have a common callable)
  • ValueError (Object of argument `exh_obj` does not have any exception trace information)
get_sphinx_autodoc(depth=None, exclude=None, width=72, error=False, raised=False, no_comment=False)

Returns an exception list marked up in reStructuredText automatically determining callable name

Parameters:
  • depth (non-negative integer or None) – Hierarchy levels to include in the exceptions list (overrides default depth argument; see putil.exdoc.ExDoc.depth). If None exceptions at all depths are included
  • exclude (list of strings or None) – List of (potentially partial) module and callable names to exclude from exceptions list (overrides default exclude argument, see putil.exdoc.ExDoc.exclude). If None all callables are included
  • width (integer) – Maximum width of the lines of text (minimum 40)
  • error (boolean) – Flag that indicates whether an exception should be raised if the callable is not found in the callables exceptions database (True) or not (False)
  • raised (boolean) – Flag that indicates whether only exceptions that were raised (and presumably caught) should be documented (True) or all registered exceptions should be documented (False)
  • no_comment (boolean) – Flag that indicates whether a reStructuredText comment labeling the callable (method, function or class property) should be printed (False) or not (True) before the exceptions documentation
Raises:
  • RuntimeError (Argument `depth` is not valid)
  • RuntimeError (Argument `error` is not valid)
  • RuntimeError (Argument `exclude` is not valid)
  • RuntimeError (Argument `no_comment` is not valid)
  • RuntimeError (Argument `raised` is not valid)
  • RuntimeError (Argument `width` is not valid)
  • RuntimeError (Callable not found in exception list: [name])
  • RuntimeError (Unable to determine callable name)
get_sphinx_doc(name, depth=None, exclude=None, width=72, error=False, raised=False, no_comment=False)

Returns an exception list marked up in reStructuredText

Parameters:
  • name (string) – Name of the callable (method, function or class property) to generate exceptions documentation for
  • depth (non-negative integer or None) – Hierarchy levels to include in the exceptions list (overrides default depth argument; see putil.exdoc.ExDoc.depth). If None exceptions at all depths are included
  • exclude (list of strings or None) – List of (potentially partial) module and callable names to exclude from exceptions list (overrides default exclude argument; see putil.exdoc.ExDoc.exclude). If None all callables are included
  • width (integer) – Maximum width of the lines of text (minimum 40)
  • error (boolean) – Flag that indicates whether an exception should be raised if the callable is not found in the callables exceptions database (True) or not (False)
  • raised (boolean) – Flag that indicates whether only exceptions that were raised (and presumably caught) should be documented (True) or all registered exceptions should be documented (False)
  • no_comment (boolean) – Flag that indicates whether a reStructuredText comment labeling the callable (method, function or class property) should be printed (False) or not (True) before the exceptions documentation
Raises:
  • RuntimeError (Argument `depth` is not valid)
  • RuntimeError (Argument `error` is not valid)
  • RuntimeError (Argument `exclude` is not valid)
  • RuntimeError (Argument `no_comment` is not valid)
  • RuntimeError (Argument `raised` is not valid)
  • RuntimeError (Argument `width` is not valid)
  • RuntimeError (Callable not found in exception list: [name])
depth

Gets or sets the default hierarchy levels to include in the exceptions per callable. For example, a function my_func() calls two other functions, get_data() and process_data(), and in turn get_data() calls another function, open_socket(). In this scenario, the calls hierarchy is:

my_func            <- depth = 0
├get_data          <- depth = 1
│└open_socket      <- depth = 2
└process_data      <- depth = 1

Setting depth=0 means that only exceptions raised by my_func() are going to be included in the documentation; Setting depth=1 means that only exceptions raised by my_func(), get_data() and process_data() are going to be included in the documentation; and finally setting depth=2 (in this case it has the same effects as depth=None) means that only exceptions raised by my_func(), get_data(), process_data() and open_socket() are going to be included in the documentation.

Return type:non-negative integer
Raises:RuntimeError (Argument `depth` is not valid)
exclude

Gets or sets the default list of (potentially partial) module and callable names to exclude from exceptions per callable. For example, ['putil.ex'] excludes all exceptions from modules putil.exh and putil.exdoc (it acts as r'putil.ex*'). In addition to these modules, ['putil.ex', 'putil.eng.peng'] excludes exceptions from the function putil.eng.peng().

Return type:list
Raises:RuntimeError (Argument `exclude` is not valid)