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> |
---|
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.
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.
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’), ‘&’)]
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.
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']}
Plugin for filtering API description dictionaries.
The __init__() method may take no arguments or keyword arguments.
Deletes specified methods from a class description (desc).
Parameters : | skips : dict or list
desc : dictionary
|
---|