Sometimes you may want to replace or modify the wrapper function ++that SWIG creates in the proxy .py file. The Python module ++in SWIG provides some features that enable you do do this. First, to ++entirely replace a proxy function you can use ++%feature("shadow"). For example: ++ ++
++
++%module example
++%rename(bar_id) bar(int,double);
++
++// Rewrite bar() to allow some nice overloading
++
++%feature("shadow") Foo::bar(int) %{
++def bar(*args):
++ if len(args) == 3:
++ return apply(examplec.Foo_bar_id,args)
++ return apply(examplec.Foo_bar,args)
++%}
++
++class Foo {
++public:
++ int bar(int x);
++ int bar(int x, double y);
++}
++
++
++
++
++Often the proxy function created by SWIG is fine, but you simply want
++to add code to it without touching the rest of the generated function
++body. For these cases SWIG provides the "pythonprepend" and
++"pythonappend" features which do exactly as their names suggest. The
++"pythonprepend" feature will insert its value at the begining of the
++proxy function, and "pythonappend" will insert code at the end of the
++proxy, just before the return statement.
++
++
+ ++++ ++The features described in this section make it easy for you to add ++docstrings to your modules, functions and methods that can then be ++used by the various tools out there to make the programming experience ++of your users much simpler. ++ ++ ++++bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL); ++++
++++ ++When you have more than just a line or so then you can retain the easy ++readability of the %module directive by using a macro. For ++example: ++ ++++%module(docstring="This is the example module's docstring") example ++++
++++ ++ ++++%define DOCSTRING ++"The `XmlResource` class allows program resources defining menus, ++layout of controls on a panel, etc. to be loaded from an XML file." ++%enddef ++ ++%module(docstring=DOCSTRING) xrc ++++
But since SWIG does know everything about the fucntion it is ++possible to generate a docstring containing the parameter types, names ++and default values. Since many of the doctring tools are adopting a ++standard of recognizing if the first thing in the docstring is a ++function prototype then using that instead of what they found from ++introspeciton, then life is good once more. ++ ++
SWIG's Python module provides support for the "autodoc" feature, ++which when attached to a node in the parse tree will cause a docstring ++to be generated that includes the name of the funciton, parameter ++names, default values if any, and return type if any. There are also ++three options for autodoc controlled by the value given to the ++feature, described below. ++ ++
++
++%feature("autodoc", "0");
++bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL);
++
++
++
++Then Python code like this will be generated:
++
++++++ ++ ++++def function_name(*args, **kwargs): ++ """function_name(x, y, foo=None, bar=None) -> bool""" ++ ... ++++
++++ ++ ++ ++++def function_name(*args, **kwargs): ++ """function_name(int x, int y, Foo foo=None, Bar bar=None) -> bool""" ++ ... ++++
++
++%feature("autodoc", "GetPosition() -> (x, y)") GetPosition;
++void GetPosition(int* OUTPUT, int* OUTPUT);
++
++
++
++
++++++ ++Otherwise, to aid readability it is output like this: ++ ++++"""This is the docstring""" ++++
++++ ++++""" ++This is a multi-line docstring ++with more than one line. ++""" ++++
++++ ++This is useful when the .i file is %imported by ++another .i file. By default SWIG will assume that the ++importer is able to find the importee with just the module name, but ++if they live in separate Python packages then that won't work. ++However if the importee specifies what its package is with the ++%module option then the Python code generated for the ++importer will use that package name when importing the other module ++and also in base class declarations, etc. if the pacakge name is ++different than its own. ++ ++ ++ +++%module(package="wx") xrc ++++