API Documentation for Venusian

class venusian.Scanner(**kw)

scan(package, categories=None, onerror=None, ignore=None)

Scan a Python package and any of its subpackages. All top-level objects will be considered; those marked with venusian callback attributes related to category will be processed.

The package argument should be a reference to a Python package or module object.

The categories argument should be sequence of Venusian callback categories (each category usually a string) or the special value None which means all Venusian callback categories. The default is None.

The onerror argument should either be None or a callback function which behaves the same way as the onerror callback function described in http://docs.python.org/library/pkgutil.html#pkgutil.walk_packages . By default, during a scan, Venusian will propagate all errors that happen during its code importing process, including ImportError. If you use a custom onerror callback, you can change this behavior.

Here’s an example onerror callback that ignores ImportError:

import sys
def onerror(name):
    if not issubclass(sys.exc_info()[0], ImportError):
        raise # reraise the last exception

The name passed to onerror is the module or package dotted name that could not be imported due to an exception.

New in version 1.0: the onerror callback

The ignore argument allows you to ignore certain modules, packages, or global objects during a scan. It should be a sequence containing strings and/or callables that will be used to match against the full dotted name of each object encountered during a scan. The sequence can contain any of these three types of objects:

• A string representing a full dotted name. To name an object by dotted name, use a string representing the full dotted name. For example, if you want to ignore the my.package package and any of its subobjects or subpackages during the scan, pass ignore=['my.package'].
• A string representing a relative dotted name. To name an object relative to the package passed to this method, use a string beginning with a dot. For example, if the package you’ve passed is imported as my.package, and you pass ignore=['.mymodule'], the my.package.mymodule mymodule and any of its subobjects or subpackages will be omitted during scan processing.
• A callable that accepts a full dotted name string of an object as its single positional argument and returns True or False. For example, if you want to skip all packages, modules, and global objects with a full dotted path that ends with the word “tests”, you can use ignore=[re.compile('tests$').search]. If the callable returns True (or anything else truthy), the object is ignored, if it returns False (or anything else falsy) the object is not ignored. Note that unlike string matches, ignores that use a callable don’t cause submodules and subobjects of a module or package represented by a dotted name to also be ignored, they match individual objects found during a scan, including packages, modules, and global objects.

You can mix and match the three types of strings in the list. For example, if the package being scanned is my, ignore=['my.package', '.someothermodule', re.compile('tests$').search] would cause my.package (and all its submodules and subobjects) to be ignored, my.someothermodule to be ignored, and any modules, packages, or global objects found during the scan that have a full dotted name that ends with the word tests to be ignored.

Note that packages and modules matched by any ignore in the list will not be imported, and their top-level code will not be run as a result.

A string or callable alone can also be passed as ignore without a surrounding list.

New in version 1.0a3: the ignore argument

class venusian.AttachInfo(**kw)

An instance of this class is returned by the venusian.attach() function. It has the following attributes:

scope

One of exec, module, class, function call or unknown (each a string). This is the scope detected while executing the decorator which runs the attach function.

module

The module in which the decorated function was defined.

locals

A dictionary containing decorator frame’s f_locals.

globals

A dictionary containing decorator frame’s f_globals.

category

The category argument passed to attach (or None, the default).

codeinfo

A tuple in the form (filename, lineno, function, sourceline) representing the context of the venusian decorator used. Eg. ('/home/chrism/projects/venusian/tests/test_advice.py', 81, 'testCallInfo', 'add_handler(foo, bar)')

venusian.attach(wrapped, callback, category=None)

Attach a callback to the wrapped object. It will be found later during a scan. This function returns an instance of the venusian.AttachInfo class.