VTK/Python Wrapper Enhancement

This project will improve the python wrappers bit-by-bit, with the goal of making the Python interface as close as possible to the original C++ interface. When each piece is finished, it will be marked as "done".

Improvements to Python wrappers

• Allow hierarchies of special types
• Enums and other constants
• Operator support
• Wrapping of templated types - will always be limited to selected types, but can still be very useful
• Wrapping of default-value arguments
• Wrapping of pointers args - requires a better hinting system
• Wrapping of reference args for returning values - would be easy
• Handle SetTuple/GetTuple methods of vtkDataArray

Hierarchies of special types in Python wrappers

If each special type had its own PyTypeObject struct (to be generated by vtkWrapPython.c) then:

• Types could have a hierarchy via python's subclass system
• Type-specific protocols (number, sequence, buffer, etc) could be supported, this would require proper parsing of operators

Also: see VTK/WrapHierarchy for a tool that provides the entire hierarchy to the wrappers at compile-time

Enums and constants

The new vtkParse will parse enums and #define constants.

• The FileInfo struct must be expanded to hold these constants
• Constant values should be stored as strings to simplify typing*
• The wrappers will have to automatically add the class scope to enum constants.

* The strings can be written literally into the wrapper .cxx files where they will be evaluated as the correct type.

Operator support

The new vtkParse provides information about operator methods for the VTK classes. These operator methods can be mirrored in Python by:

1. defining the appropriate "protocols" for special type objects
2. defining the proper methods e.g. __setitem__() for vtkObjectBase objects

Each VTK special type will have its own python "type" object, and can thus support its own set of protocols which will automatically be inherited by "subtypes". All vtkObjectBase objects have the same python "type" object so protocols cannot be used, the less-efficient technique of using underscore methods can be applied.

Templated type handling in Python

Should be made to look similar to numpy, e.g. vtkValue(1, 'f') would create a vtkValue<float>. To python, the templated type would look like a variadic type. It would be necessary to change vtkParse so that it recognized templates.

Default value arguments

Default argument value support would require the following:

1. vtkParse must store the default value in the FunctionInfo struct as a string*
2. vtkWrapPython.c must use these default values to initialize parameter values
3. vtkWrapPython.c must place a bar "|" before the default args in the ParseTuple format string
4. some other small changes would be needed

* the default value must be stored as a string to accommodate all types and to accommodate simple mathematical expressions, e.g. the default might be SomeMethod(int param = VTK_CONST1 - VTK_CONST2). The string "VTK_CONST1 - VTK_CONST2" can be dropped directly into the wrapper CXX code where it will be evaluated.

Pointer arg wrapping

The "count" for pointer args should be hinted so that they can be properly wrapped. E.g.

1. vtkVariant::ToInt(bool *vtkSingleValue(valid))
2. vtkVariant::ToInt(bool *vtkOptionalSingleValue(valid)) - can be safely set to NULL
3. vtkDataArray::SetTuple(double *vtkMultiValue(tuple, GetNumberOfComponents))

In the latter, the name of the method to get the count is supplied in the hint. Recognizing these macros in vtkParse would be easy.

Reference arg wrapping: &arg

This is trivial to add, only a few lines would have to be added to vtkWrapPython. For the reference arg, the user would have to pass a container object that supported both the sequence protocol and the number protocol, e.g. like a numpy array. For example, the user could make an array([0], 'f') and pass it, and after the call the result would be stored in the array.

GetTuple/SetTuple

The wrappers should make a "special case" for vtkDataArray and wrap the GetTuple/SetTuple methods using the knowledge that the tuple size is equal to the number of components. The same can be done for the subclasses, with GetTupleValue/SetTupleValue. This is a change that could also be easily done for Tcl and Java.