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, name=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.

category should be None or a string representing a decorator category name.

name should be None or a string representing a subcategory within the category. This will be used by the lift class decorator to determine if decorations of a method should be inherited or overridden.

class venusian.lift(categories=None)

A class decorator which ‘lifts’ superclass venusian configuration decorations into subclasses. For example:

from venusian import lift
from somepackage import venusian_decorator

class Super(object):
    @venusian_decorator()
    def boo(self): pass

    @venusian_decorator()
    def hiss(self): pass

    @venusian_decorator()
    def jump(self): pass
        
@lift()
class Sub(Super):
    def boo(self): pass

    def hiss(self): pass
    
    @venusian_decorator()
    def smack(self): pass

The above configuration will cause the callbacks of seven venusian decorators. The ones attached to Super.boo, Super.hiss, and Super.jump plus ones attached to Sub.boo, Sub.hiss, Sub.hump and Sub.smack.

If a subclass overrides a decorator on a method, its superclass decorators will be ignored for the subclass. That means that in this configuration:

from venusian import lift
from somepackage import venusian_decorator

class Super(object):
    @venusian_decorator()
    def boo(self): pass

    @venusian_decorator()
    def hiss(self): pass

@lift()
class Sub(Super):

    def boo(self): pass
    
    @venusian_decorator()
    def hiss(self): pass

Only four, not five decorator callbacks will be run: the ones attached to Super.boo and Super.hiss, the inherited one of Sub.boo and the non-inherited one of Sub.hiss. The inherited decorator on Super.hiss will be ignored for the subclass.

The lift decorator takes a single argument named ‘categories’. If supplied, it should be a tuple of category names. Only decorators in this category will be lifted if it is suppled.

class venusian.onlyliftedfrom

A class decorator which marks a class as ‘only lifted from’. Decorations made on methods of the class won’t have their callbacks called directly, but classes which inherit from only-lifted-from classes which also use the lift class decorator will use the superclass decoration callbacks.

For example:

from venusian import lift, onlyliftedfrom
from somepackage import venusian_decorator

@onlyliftedfrom()
class Super(object):
    @venusian_decorator()
    def boo(self): pass

    @venusian_decorator()
    def hiss(self): pass

@lift()
class Sub(Super):

    def boo(self): pass
    
    def hiss(self): pass

Only two decorator callbacks will be run: the ones attached to Sub.boo and Sub.hiss. The inherited decorators on Super.boo and Super.hiss will be not be registered.