Python Packages
@@ -2460,9 +2467,8 @@
customization features as covered in later sections.
26.6.2 Adding additional Python code
-
If writing support code in C isn't enough, it is also possible to write code in
Python. This code gets inserted in to the .py file created by SWIG. One
use of Python code might be to supply a high-level interface to certain functions.
For example:
@@ -2506,8 +2512,46 @@
soon enough. For now, think of this example as an illustration of
what can be done without having to rely on any of the more advanced
customization features.
+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.
+
+
26.6.3 Class extension with %extend
One of the more interesting features of SWIG is that it can extend
@@ -3852,6 +3896,197 @@
that has a this attribute. In addition,
SWIG_NewPointerObj() can automatically generate a proxy
class object (if applicable).
+
+
+26.10 Docstring Features
+
+Usign docstrings in Python code is becoming more and more important
+ans more tools are coming on the scene that take advantage of them,
+everything from full-blown documentaiton generators to class browsers
+and popup call-tips in Python-aware IDEs. Given the way that SWIG
+generates the proxy code by default, your users will normally get
+something like "function_name(*args)" in the popup calltip of
+their IDE which is next to useless when the real function prototype
+might be something like this:
+
+
+
+bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL);
+
+
+
+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.
+
+
+26.10.1 Module docstring
+
+Python allows a docstring at the begining of the .py file
+before any other statements, and it is typically used to give a
+general description of the entire module. SWIG supports this by
+setting an option of the %module directive. For example:
+
+
+
+%module(docstring="This is the example module's docstring") example
+
+
+
+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:
+
+
+
+%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
+
+
+
+
+26.10.2 %feature("autodoc")
+
+As alluded to above SWIG will generate all the function and method
+proxy wrappers with just "*args" (or "*args, **kwargs" if the -keyword
+option is used) for a parameter list and will then sort out the
+individual parameters in the C wrapper code. This is nice and simple
+for the wrapper code, but makes it difficult to be programmer and tool
+friendly as anyone looking at the .py file will not be able
+to find out anything about the parameters that the fuctions accept.
+
+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")
+
+When the "0" option is given then the types of the parameters will
+not be included in the autodoc string. For example, given
+this function prototype:
+
+
+
+%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"""
+ ...
+
+
+
+
+%feature("autodoc", "1")
+
+When the "1" option is used then the parameter types will be
+used in the autodoc string. In addition, an atempt is made to
+simplify the type name such that it makes more sense to the Python
+user. Pointer, reference and const info is removed,
+%rename's are evaluated, etc. (This is not always
+successful, but works most of the time. See the next section for what
+to do when it doesn't.) Given the example above, then turning on the
+parameter types with the "1" option will result in Python code like
+this:
+
+
+
+def function_name(*args, **kwargs):
+ """function_name(int x, int y, Foo foo=None, Bar bar=None) -> bool"""
+ ...
+
+
+
+
+
+%feature("autodoc", "docstring")
+
+Finally, there are times when the automatically generated autodoc
+string will make no sense for a Python programmer, particularly when a
+typemap is involved. So if you give an explicit value for the autodoc
+feature then that string will be used in place of the automatically
+generated string. For example:
+
+
+
+%feature("autodoc", "GetPosition() -> (x, y)") GetPosition;
+void GetPosition(int* OUTPUT, int* OUTPUT);
+
+
+
+
+26.10.3 %feature("docstring")
+
+In addition to the autodoc strings described above, you can also
+attach any arbitrary descriptive text to a node in the parse tree with
+the "docstring" feature. When the proxy module is generated then any
+docstring associated with classes, function or methods are output.
+If an item already has an autodoc string then it is combined with the
+docstring and they are output together. If the docstring is all on a
+single line then it is output like this::
+
+
+
+"""This is the docstring"""
+
+
+
+Otherwise, to aid readability it is output like this:
+
+
+
+"""
+This is a multi-line docstring
+with more than one line.
+"""
+
+
+
+26.11 Python Packages
+
+Using the package option of the %module directive
+allows you to specify what Python package that the module will be
+living in when installed.
+
+
+
+%module(package="wx") xrc
+
+
+
+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.
+
+
+