(Python programming) Integrated code generator Swig

Programming Python, 3rd Edition translation
See the latest version: Http://wiki.woodpecker.org.cn/moin/PP3eD

22.6. The SWIG Integration Code generator

22.6. Integrated code generator Swig

But don ' t does that. As can probably tell, manual coding of the C extensions can become fairly involved (this are almost inevitable in C LANGUAG e work). I ' ve introduced the basics in this chapter thus far the understand. But today, C extensions are usually better and more easily implemented with a tool this generates all required tion glue code automatically. There are a variety of such tools for use in the Python world, including SIP, SWIG, and Boost.python; We ' ll explore alternatives at the end of this chapter. Of these, the SWIG system is likely still the most widely used.

But we don't have to code manually. As you know, it's quite complicated to write a C extension manually (that's what the C language job is). So far, the content in this chapter is just a basic knowledge to help you understand the underlying constructs. Today, C extensions typically use tools to automatically generate all of the integrated glue code, which is much easier than manual implementations. There are many such tools, such as SIP, SWIG, and Boost.python, and we will explore various tools at the end of this chapter. Among them, swig may be the most widely used tool.

The simplified wrapper and Interface Generator (SWIG) is a open source system created by Dave Beazley and now developed B Y its community is much like Python. It uses C and C + + type declarations to generate complete C extension modules that integrate existing Python scripts. The generated C (and C + +) extension modules are complete:they automatically handle data conversion, error protocols, Refe Rence-count management, and more.

SWIG (simple encapsulation and Interface Builder) is an open source system created by Dave Beazley and is now developed by its community, much like Python. It uses C and C + + type declarations to generate a complete C extension module that can be integrated into an existing library for use by Python scripts. The generated C (and C + +) extension modules are complete: They automatically handle data transformations, error handling, reference counts, and so on.

This is, SWIG are a program that automatically generates the glue code needed to plug C and C + + components into Python Programs Simply run SWIG, compile its output, and your extension work are done. You are still have to manage compilation and linking details, but the rest of the C extension task are largely performed by SWI G.

That is, Swig is a program that automatically generates all the glue code, inserts C and C + + parts into the Python program, and simply runs the swig, compiles its output code, and your extension module is complete. You still have to compile and link, but most of the other work on C extensions can be done by swig.

22.6.1. A Simple SWIG Example

22.6.1. A simple example of a swig

To use SIWG, instead of writing all, "C code in the prior sections, write the" C function "you want" to "use" from Python WI Thout any Python integration logic in all, as though it being to being used from C alone. For instance, Example 22-5 is a recoding of Example 22-1 as a straight C function.

With Swig, you don't have to have any Python-integrated logic, you don't have to write the code in the previous sections, you just write your C function, just as it is for the C language. For example, example 22-5 is an override of example 22-1, which is a pure C function.

Example 22-5. Pp3e/integrate/extend/hellolib/hellolib.c
/**/ /*********************************************************************
* A simple C library file, with a single function, "message",
* which is to be made available for use in Python programs.
* There is nothing about Python here--this C function can
* Called from a C program, as OK as Python (with glue code).
*
* A simple C language library file, only one function, "message",
* will become a function that can be used by Python programs.
* There's no python-related stuff here--this C function can
* Called by the C program, or can be called by the Python program (plus the Glue code).
*********************************************************************/

#include < string. h >
#include < hellolib.h >

Static char result[64]; /**//* This isn ' t exported * *

char *
Message (char * label)/**//* This is exported * *
... {
strcpy (Result, "Hello,"); /**//* build Up C String * *
strcat (result, label); /**//* Add passed-in Label * *
return result; /**//* return a temporary * *
}

While you are at it, define the "usual C header file to declare" function externally, as shown in Example 22-6. This is probably overkill for such a small example, but it'll prove a point.

Then, write an ordinary header file to declare the external function, as shown in example 22-6. For such a small example, this may seem superfluous, but the following will be used.

Example 22-6. Pp3e/integrate/extend/hellolib/hellolib.h
/**/ /********************************************************************
* Define HELLOLIB.C exports to the "C namespace", not to Python
* Programs--the latter is defined by a method registration
* table in a Python extension module ' s code, not by this. h;
*
* Define the HELLOLIB.C output to the C language (not output to the Python program).
* The symbols exported to the Python program are defined by a method registry in the Python Extension module code,
* And not in this. h file.
********************************************************************/

extern char * Message (char * label);

Now, instead of the "all" Python extension glue code shown in the prior, sections write a simply type SWIG T file, as in Example 22-7.

Now, without all the Python extension glue code shown in the previous sections, simply write a swig type declaration input file, as in example 22-7.

Example 22-7. Pp3e/integrate/extend/swig/hellolib.i
/**/ /******************************************************
* Swig Module description file, for a C lib file.
* Generate by saying "Swig-python hellolib.i".
******************************************************/

% Module Hellowrap

% ... {
#include %}

extern char * message (char *); /**//* OR:%include. /hellolib/hellolib.h "* *
/**//* OR:%include hellolib.h, and use-i ARG * * *


This file spells out the C function ' s type signature. In general, SWIG scans files containing ANSI C and C + + declarations. Its input file can take the form of a interface description file (usually with a. I suffix) or a C + + header or source F Ile. Interface files like this one are the most common input form; They can contain comments in C or C + + format, type declarations just like standard header files, and SWIG All start with%. For example:

This file lists the type signatures of the C function. Typically, swig needs to scan files containing ANSI C and C + + declarations, and its input file can be an interface description file (usually the. i suffix), or a C + + header file or source file. The interface file is the most common form, like this one, can contain a C or C + + format annotation, a type declaration like a standard header file, and a swig instruction that starts with a%. For example:

%module

Sets the module ' s name as known to Python importers.

%module sets the module name, which is the name that Python imports.

%{...%}

Encloses code added to generated wrapper file verbatim.

The code enclosed in%{...% will be added to the generated wrapper file intact.

extern statements

Declare exports in normal ANSI/C + + syntax.

An extern statement declares the output of a symbol in the standard ANSI/C + + syntax.

%include

Makes SWIG scan another file (-I-flags give search paths).

The%include command Swig scan another file (the search path can be given with the-I flag).

In this example, SWIG could also is made to read the Hellolib.h header file of example 22-6. But one of the advantages of writing special SWIG input files like hellolib.i are that you can pick and choose which ONS are wrapped and exported to Python, and you have the directives to gain the process.

In this case, Swig can also read the Hellolib.h header file for example 22-6 directly. But there is at least one advantage in writing a swig input file like HELLOLIB.I, which is that you can pick which functions to encapsulate and output to Python, and you can use instructions to better control the generation of the code.

SWIG is a utility program which you run from your build scripts; It is isn't a programming language, so there are not very much. Simply Add a step to your makefile the runs SWIG and compile its output to is linked with Python. Example 22-8 shows one way to does it on Cygwin.

Swig is a general-purpose program called by the build script, and it's not a programming language, so there's nothing to talk about. Simply add a step to run swig in the make file, and then compile the Swig output and link to Python. Example 22-8 shows the practice on the Cygwin.

Example 22-8. Pp3e/integrate/extend/swig/makefile.hellolib-swig
##################################################################
# Use SWIG to integrate HELLOLIB.C