API Documentation for Venusian¶
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
categorywill be processed.
packageargument should be a reference to a Python package or module object.
categoriesargument should be sequence of Venusian callback categories (each category usually a string) or the special value
Nonewhich means all Venusian callback categories. The default is
onerrorargument should either be
Noneor a callback function which behaves the same way as the
onerrorcallback 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
onerrorcallback, you can change this behavior.
Here’s an example
onerrorcallback that ignores
import sys def onerror(name): if not issubclass(sys.exc_info(), ImportError): raise # reraise the last exception
onerroris the module or package dotted name that could not be imported due to an exception.
New in version 1.0: the
ignoreargument 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.packagepackage and any of its subobjects or subpackages during the scan, pass
- A string representing a relative dotted name. To name an object
relative to the
packagepassed to this method, use a string beginning with a dot. For example, if the
packageyou’ve passed is imported as
my.package, and you pass
my.package.mymodulemymodule 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
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
ignore=['my.package', '.someothermodule', re.compile('tests$').search]would cause
my.package(and all its submodules and subobjects) to be ignored,
my.someothermoduleto be ignored, and any modules, packages, or global objects found during the scan that have a full dotted name that ends with the word
teststo 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
ignorewithout a surrounding list.
New in version 1.0a3: the
- 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
An instance of this class is returned by the
venusian.attach()function. It has the following attributes:
unknown(each a string). This is the scope detected while executing the decorator which runs the attach function.
moduleThe module in which the decorated function was defined.
localsA dictionary containing decorator frame’s f_locals.
globalsA dictionary containing decorator frame’s f_globals.
categoryargument passed to
None, the default).
codeinfoA 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(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
Noneor a string representing a decorator category name.
Noneor a string representing a subcategory within the category. This will be used by the
liftclass 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.
liftdecorator 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
liftclass 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.