Description Filter¶

Filters parsed code to exclude methods or attributes that have certain types as input parameters.

This module is available as the xdress plugin xdress.descfilter.

author:	Spencer Lyon <spencerlyon2@gmail.com>

Filtering¶

This plugin alters the description dictionary generated by other xdress plugins (mainly xdress.autodescribe) by removing attributes or methods that contain argument types the user wishes to exclude from the generated cython wrapper. To use xdress.descfilter, you need to do two things in the xdressrc file for your project.

Add it to the list of plugins
Define one or more of the following:
1. skiptpyes, a list or dictionary. If skiptypes is a dictionary the keys are class names and the values are lists (or tuples) of data types that should be left out of the generated code for the class. If skiptypes is a list or tuple, the skipped types will be applied to all classes listed in the classes list in xdressrc. If skiptypes is empty or None this plugin will not try to filter any types.
2. skipmethods dictionary. The keys for this dictionary are the class names and the values are a list of method names that should be excluded from the wrapper.
3. skipattrs dictionary. The keys for this dictionary are the class names and the values are a list of class attributes that should be excluded from the wrapper.
4. includemethods dict. This is the complement of the skipmethods dict. The keys are class names and the values are list of methods that should be included in the wrapper. All other methods are filtered out.
5. skipauto boolean. If this is True then methods and attributes with any types that are unknown will be filtered out.

Warning

It is important that xdress.descfilter comes after xdress.autoall, and xdress.autodescribe but before xdress.cythongen. This is necessary because the description dictionary needs to be populated by autodescribe before descfilter can act on it, but it also must do the filtering before cythongen generates any code.

Type Filtering Example¶

To filter specific types you might do something like this in xdressrc:

# Declare use of plugin (point 1)
plugins = ('xdress.stlwrap', 'xdress.autoall', 'xdress.autodescribe',
           'xdress.descfilter', 'xdress.cythongen')

# Specify skiptypes (point 2)
skiptypes = {'classA': ['float64', (('int32', 'const'), '&')],
             'classB': ['classA', ('vector', 'float32')]}

I also could have done the following to exclude all instances of particular types, regardless of the class in which they arise.

skiptypes = [‘uint32’, ((‘vector’, ‘float64’, ‘const’), ‘&’)]

A Closer Look¶

As of right now xdress.descfilter is set up to handle skiptype elements of two flavors.

A single type identifier. This could be any base type, (e.g. int32, char, float64, ect), an STL type (e.g. vector, map, set), or any type xdress knows about (like classA in the first example above). In this case xdress will flatten all argument types and if the single type identifier appears anywhere in the flattened argument description, the method will be filtered out.

For example, if ‘float64’ were in the skiptypes it would catch any of the following argument types (this is by no means a complete list):
```
"float64"
(('vector', 'float64', 'const'), '&')
('set', 'float64')
```
A specific argument or return type that will match exactly. This option provides more control over what xdress.descfilter will catch and can prevent the plugin from being to ambitious with regards to the methods that are filtered out.

Typically, the first option would be used in situations where xdress, for whatever reason, cannot create a wrapper for a user-defined C++ class. This might happen due to limitations with xdress itself, or perhaps limitations with Cython.

Users are advised to use the second option in most other circumstances in order to forestall any potential issues with needed methods not being wrapped.

Method Filtering Example¶

Suppose, in the C++ source, I had a class Computer with the following methods:

checkEmail turnOn blowUp runXdress sleep crash

Now, if I didn’t want python users to have access to the blowUp, sleep, or crash methods, I would put the following in my xdressrc file:

# Declare use of plugin (point 1)
plugins = ('xdress.stlwrap', 'xdress.autoall', 'xdress.autodescribe',
           'xdress.methodfilter', 'xdress.cythongen')

# Specify methods to skip (point 2)
skipmethods = {'Computer': ['blowUp', 'sleep', 'crash']}