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(), 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:
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
An instance of this class is returned by the venusian.attach() function. It has the following attributes:
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.
The module in which the decorated function was defined.
A dictionary containing decorator frame’s f_locals.
A dictionary containing decorator frame’s f_globals.
The category argument passed to attach (or None, the default).
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)')
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.
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.
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.
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.