exh module

This module can be used to register exceptions and then raise them if a given condition is true. For example:

# exh_example.py
from __future__ import print_function
from pexdoc.exh import addex


def my_func(name):
    """Sample function."""
    # Add exception
    exobj = addex(TypeError, "Argument `name` is not valid")
    # Conditionally raise exception
    exobj(not isinstance(name, str))
    print("My name is {0}".format(name))

>>> import docs.support.exh_example
>>> docs.support.exh_example.my_func('Tom')
My name is Tom
>>> docs.support.exh_example.my_func(5) 
Traceback (most recent call last):
    ...
TypeError: Argument `name` is not valid

When my_func() gets called with anything but a string as an argument a TypeError exception is raised with the message 'Argument `name` is not valid'. While adding an exception with pexdoc.exh.addex() and conditionally raising it takes the same number of lines of code as an exception raised inside an if block (or less since the raise condition can be evaluated in the same pexdoc.exh.addex() call) and incurs a slight performance penalty, using the pexdoc.exh module allows for automatic documentation of the exceptions raised by any function, method or class property with the help of the pexdoc.exdoc module.

Functions

pexdoc.exh.addex(extype, exmsg, condition=None, edata=None)

Add an exception in the global exception handler.

Parameters:
  • extype (Exception type object, i.e. RuntimeError, TypeError, etc.) – Exception type; must be derived from the Exception class
  • exmsg (string) – Exception message; it can contain fields to be replaced when the exception is raised via pexdoc.ExHandle.raise_exception_if(). A field starts with the characters '*[' and ends with the characters ']*', the field name follows the same rules as variable names and is between these two sets of characters. For example, '*[fname]*' defines the fname field
  • condition (boolean or None) – Flag that indicates whether the exception is raised (True) or not (False). If None the flag is not used an no exception is raised
  • edata –

    Replacement values for fields in the exception message (see pexdoc.ExHandle.add_exception() for how to define fields). Each dictionary entry can only have these two keys:

    • field (string) – Field name
    • value (any) – Field value, to be converted into a string with the format string method

    If None no field replacement is done
Return type:

(if condition is not given or None) function
Raises:
  • RuntimeError (Argument `condition` is not valid)
  • RuntimeError (Argument `edata` is not valid)
  • RuntimeError (Argument `exmsg` is not valid)
  • RuntimeError (Argument `extype` is not valid)
pexdoc.exh.addai(argname, condition=None)

Add an “AI” exception in the global exception handler.

An “AI” exception is of the type RuntimeError('Argument `*[argname]*` is not valid') where *[argname]* is the value of the argname argument

Parameters:
  • argname (string) – Argument name
  • condition (boolean or None) – Flag that indicates whether the exception is raised (True) or not (False). If None the flag is not used and no exception is raised
Return type:

(if condition is not given or None) function
Raises:
  • RuntimeError (Argument `argname` is not valid)
  • RuntimeError (Argument `condition` is not valid)
pexdoc.exh.get_exh_obj()

Return the global exception handler.

Return type:pexdoc.ExHandle if global exception handler is set, None otherwise
pexdoc.exh.get_or_create_exh_obj(full_cname=False, exclude=None, callables_fname=None)

Return global exception handler if set, otherwise create a new one and return it.

Parameters:
  • full_cname (boolean) –

    Flag that indicates whether fully qualified function/method/class property names are obtained for functions/methods/class properties that use the exception manager (True) or not (False).

    There is a performance penalty if the flag is True as the call stack needs to be traced. This argument is only relevant if the global exception handler is not set and a new one is created

  • 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
  • callables_fname (FileNameExists or None) – File name that contains traced modules information. File can be produced by either the pexdoc.pinspect.Callables.save() or pexdoc.ExHandle.save_callables() methods
Return type:

pexdoc.ExHandle
Raises:
  • OSError (File [callables_fname] could not be found
  • RuntimeError (Argument `exclude` is not valid)
  • RuntimeError (Argument `callables_fname` is not valid)
  • RuntimeError (Argument `full_cname` is not valid)
pexdoc.exh.del_exh_obj()

Delete global exception handler (if set).

pexdoc.exh.set_exh_obj(obj)

Set the global exception handler.

Parameters:obj (pexdoc.ExHandle) – Exception handler
Raises:RuntimeError (Argument `obj` is not valid)

Classes

class pexdoc.exh.ExHandle(full_cname=False, exclude=None, callables_fname=None)

Bases: object

Create exception handler.

Parameters:
  • full_cname (boolean) –

    Flag that indicates whether fully qualified function/method/class property names are obtained for functions/methods/class properties that use the exception manager (True) or not (False).

    There is a performance penalty if the flag is True as the call stack needs to be traced

  • 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
  • callables_fname (FileNameExists or None) – File name that contains traced modules information. File can be produced by either the pexdoc.pinspect.Callables.save() or pexdoc.ExHandle.save_callables() methods
Return type:

pexdoc.ExHandle
Raises:
  • OSError (File [callables_fname] could not be found
  • RuntimeError (Argument `exclude` is not valid)
  • RuntimeError (Argument `callables_fname` is not valid)
  • RuntimeError (Argument `full_cname` is not valid)
  • ValueError (Source for module [module_name] could not be found)
__add__(other)

Merge two objects.

Raises:
  • RuntimeError (Incompatible exception handlers)
  • TypeError (Unsupported operand type(s) for +: pexdoc.ExHandle and [other_type])

For example:

>>> import copy, pexdoc
>>> @pexdoc.contract(num=int)
... def mynumber(num):
...     return num+1
>>> @pexdoc.contract(char=str)
... def mystring(char):
...     return 'Hello '+char
>>> pexdoc.set_exh_obj(pexdoc.ExHandle())
>>> mynumber(1)
2
>>> mystring('Tom')
'Hello Tom'
>>> obj1 = copy.copy(pexdoc.get_exh_obj())
>>> pexdoc.del_exh_obj()
>>> exhobj = pexdoc.get_or_create_exh_obj()
>>> mynumber(1)
2
>>> obj2 = copy.copy(pexdoc.get_exh_obj())
>>> pexdoc.del_exh_obj()
>>> exhobj = pexdoc.get_or_create_exh_obj()
>>> mystring('Tom')
'Hello Tom'
>>> obj3 = copy.copy(pexdoc.get_exh_obj())
>>> obj1 == obj2
False
>>> obj1 == obj3
False
>>> obj1 == obj2+obj3
True
__bool__()

Return False if exception handler is empty, True otherwise.

Note

This method applies to Python 3.x

For example:

>>> from __future__ import print_function
>>> import pexdoc
>>> obj = pexdoc.ExHandle()
>>> if obj:
...     print('Boolean test returned: True')
... else:
...     print('Boolean test returned: False')
Boolean test returned: False
>>> def my_func(exhobj):
...     exhobj.add_exception('test', RuntimeError, 'Message')
>>> my_func(obj)
>>> if obj:
...     print('Boolean test returned: True')
... else:
...     print('Boolean test returned: False')
Boolean test returned: True
__copy__()

Copy object.

For example:

>>> import copy, pexdoc
>>> @pexdoc.contract(num=int)
... def mynumber(num):
...     return num+1
>>> exhobj = pexdoc.set_exh_obj(pexdoc.ExHandle())
>>> mynumber(1)
2
>>> obj1 = pexdoc.get_exh_obj()
>>> obj2 = copy.copy(obj1)
>>> obj1 == obj2
True
__eq__(other)

Test object equality.

For example:

>>> import copy, pexdoc
>>> @pexdoc.contract(num=int)
... def mynumber(num):
...     return num+1
>>> exhobj = pexdoc.set_exh_obj(pexdoc.ExHandle())
>>> mynumber(1)
2
>>> obj1 = pexdoc.get_exh_obj()
>>> obj2 = copy.copy(obj1)
>>> obj1 == obj2
True
>>> 5 == obj1
False
__iadd__(other)

Merge an object into an existing object.

Raises:
  • RuntimeError (Incompatible exception handlers)
  • TypeError (Unsupported operand type(s) for +: pexdoc.ExHandle and [other_type])

For example:

>>> import copy, pexdoc
>>> @pexdoc.contract(num=int)
... def mynumber(num):
...     return num+1
>>> @pexdoc.contract(char=str)
... def mystring(char):
...     return 'Hello '+char
>>> exhobj = pexdoc.set_exh_obj(pexdoc.ExHandle())
>>> mynumber(1)
2
>>> mystring('Tom')
'Hello Tom'
>>> obj1 = copy.copy(pexdoc.get_exh_obj())
>>> pexdoc.del_exh_obj()
>>> exhobj = pexdoc.get_or_create_exh_obj()
>>> mynumber(1)
2
>>> obj2 = copy.copy(pexdoc.get_exh_obj())
>>> pexdoc.del_exh_obj()
>>> exhobj = pexdoc.get_or_create_exh_obj()
>>> mystring('Tom')
'Hello Tom'
>>> obj3 = copy.copy(pexdoc.get_exh_obj())
>>> obj1 == obj2
False
>>> obj1 == obj3
False
>>> obj2 += obj3
>>> obj1 == obj2
True
__nonzero__()

Return False if exception handler is empty, True otherwise.

Note

This method applies to Python 2.7

For example:

>>> from __future__ import print_function
>>> import pexdoc
>>> obj = pexdoc.ExHandle()
>>> if obj:
...     print('Boolean test returned: True')
... else:
...     print('Boolean test returned: False')
Boolean test returned: False
>>> def my_func(exhobj):
...     exhobj.add_exception('test', RuntimeError, 'Message')
>>> my_func(obj)
>>> if obj:
...     print('Boolean test returned: True')
... else:
...     print('Boolean test returned: False')
Boolean test returned: True
__str__()

Return a string with a detailed description of the object’s contents.

For example:

>>> from __future__ import print_function
>>> import docs.support.exh_example
>>> pexdoc.del_exh_obj()
>>> docs.support.exh_example.my_func('Tom')
My name is Tom
>>> print(str(pexdoc.get_exh_obj())) #doctest: +ELLIPSIS
Name    : ...
Type    : TypeError
Message : Argument `name` is not valid
Function: None
add_exception(exname, extype, exmsg)

Add an exception to the handler.

Parameters:
  • exname (non-numeric string) – Exception name; has to be unique within the namespace, duplicates are eliminated
  • extype (Exception type object, i.e. RuntimeError, TypeError, etc.) –

    Exception type; must be derived from the Exception class

  • exmsg (string) – Exception message; it can contain fields to be replaced when the exception is raised via pexdoc.ExHandle.raise_exception_if(). A field starts with the characters '*[' and ends with the characters ']*', the field name follows the same rules as variable names and is between these two sets of characters. For example, '*[fname]*' defines the fname field
Return type:

tuple

The returned tuple has the following items:

  • callable id (string) first returned item, identification (as reported by the id built-in function) of the callable where the exception was added
  • exception definition (tuple), second returned item, first item is the exception type and the second item is the exception message
  • callable name (string), third returned item, callable full name (encoded with the ExHandle.encode_call() method
Raises:
  • RuntimeError (Argument `exmsg` is not valid)
  • RuntimeError (Argument `exname` is not valid)
  • RuntimeError (Argument `extype` is not valid)
decode_call(call)

Replace callable tokens with callable names.

Parameters:call (string) – Encoded callable name
Return type:string
encode_call(call)

Replace callables with tokens to reduce object memory footprint.

A callable token is an integer that denotes the order in which the callable was encountered by the encoder, i.e. the first callable encoded is assigned token 0, the second callable encoded is assigned token 1, etc.

Parameters:call (string) – Callable name
Return type:string
raise_exception_if(exname, condition, edata=None)

Raise exception conditionally.

Parameters:
  • exname (string) – Exception name
  • condition (boolean) – Flag that indicates whether the exception is raised (True) or not (False)
  • edata (dictionary, iterable of dictionaries or None) –

    Replacement values for fields in the exception message (see pexdoc.ExHandle.add_exception() for how to define fields). Each dictionary entry can only have these two keys:

    • field (string) – Field name
    • value (any) – Field value, to be converted into a string with the format string method

    If None no field replacement is done
Raises:
  • RuntimeError (Argument `condition` is not valid)
  • RuntimeError (Argument `edata` is not valid)
  • RuntimeError (Argument `exname` is not valid)
  • RuntimeError (Field [field_name] not in exception message)
  • ValueError (Exception name [name] not found’)
save_callables(callables_fname)

Save traced modules information to a JSON file.

If the file exists it is overwritten

Parameters:callables_fname (FileName) – File name
Raises:RuntimeError (Argument `callables_fname` is not valid)
callables_db

Return the callables database of the modules using the exception handler, as reported by pexdoc.pinspect.Callables.callables_db()

callables_separator

Return the character ('/') used to separate the sub-parts of fully qualified function names in pexdoc.ExHandle.callables_db() and name key in pexdoc.ExHandle.exceptions_db()

exceptions_db

Return the exceptions database. This database is a list of dictionaries that contain the following keys:

  • name (string) – Exception name of the form '[callable_identifier]/[exception_name]'. The contents of [callable_identifier] depend on the value of the argument full_cname used to create the exception handler.

    If full_cname is True, [callable_identifier] is the fully qualified callable name as it appears in the callables database (pexdoc.ExHandle.callables_db()).

    If full_cname is False, then [callable_identifier] is a decimal string representation of the callable’s code identifier as reported by the id() function.

    In either case [exception_name] is the name of the exception provided when it was defined in pexdoc.ExHandle.add_exception() (exname argument)

  • data (string) – Text of the form '[exception_type] ([exception_message])[raised]' where [exception_type] and [exception_message] are the exception type and exception message, respectively, given when the exception was defined by pexdoc.ExHandle.add_exception() (extype and exmsg arguments); and raised is an asterisk ('*') when the exception has been raised via pexdoc.ExHandle.raise_exception_if(), the empty string ('') otherwise