SWIG (Simplified Wrapper and Interface Generator)

Warnings

• breaking SWIG 4.4.0 changed the default generation of static types to heap types and introduced multi-phase module initialization for modern Python wrappers. This might require adjustments in older build systems or specific configurations, especially for projects relying on specific Python C API internals.
  Fix: Review your build system and generated wrapper code for compatibility with heap types and multi-phase initialization. If using `Py_LIMITED_API`, ensure compatibility, as fixes for combinations with recent Python versions were added in 4.4.1.
• gotcha When importing multiple SWIG-generated modules using `from <module> import *`, you might encounter a name clash on the special `cvar` object used to access global variables. This means only the `cvar` from the last loaded module will be accessible directly.
  Fix: Avoid `from <module> import *` when dealing with multiple SWIG modules. Instead, use `import <module_name>` and access global variables via `<module_name>.cvar.<variable_name>`.
• gotcha The generated Python shared library filename must precisely match the module name specified in the SWIG interface file (`%module <module_name>`), typically with a leading underscore (e.g., `_example.so` for `%module example`). A mismatch will lead to import errors.
  Fix: Ensure your compilation/linking step creates a shared library named `_<module_name>.so` (or `_<module_name>.pyd` on Windows) that matches the `%module` directive in your `.i` file.
• gotcha Memory leaks can occur when SWIG wraps C/C++ pointers to opaque types (e.g., `HWND*` on Windows) and doesn't find a corresponding destructor. SWIG treats them as raw pointers without proper memory management.
  Fix: Provide explicit definitions for opaque types (e.g., `typedef void* HWND;` in the interface file) or use custom typemaps to instruct SWIG on how to manage the memory for such pointers, for instance, by treating handles as integers.
• gotcha Issues can arise when C++ callbacks pass references to parameters that are then accessed in Python. The underlying C++ type might not correctly align with the Python instance, leading to errors when attempting to access methods of the referenced object in Python.
  Fix: Carefully ensure that C++ namespaces are correctly set in your SWIG interface file, especially when dealing with classes and callbacks that pass parameters by reference. This helps SWIG correctly map the C++ types to their Python representations.

Install

• pip install swig Install SWIG (might build from source)
• sudo apt-get install swig Install SWIG on Debian/Ubuntu (recommended for the tool)
• brew install swig Install SWIG on macOS (recommended for the tool)

Imports

• <module_name>

  import <module_name>

  SWIG generates Python modules (e.g., `_example.so` and `example.py` from `example.i`) that are then imported. There is no central 'swig' module to import for core functionality; SWIG is a code generation tool.

Quickstart

This quickstart demonstrates the full SWIG workflow: defining C/C++ functions, creating a SWIG interface file (`.i`), using the `swig` command to generate Python wrapper code and a Python module file, compiling the C/C++ source with the generated wrapper, linking them into a shared library, and finally importing and using the module in Python. Note that the compilation commands (g++) are platform-dependent and assume a C++ compiler and Python development headers are installed.

/* C/C++ file: example.h */
#ifndef EXAMPLE_H
#define EXAMPLE_H

int fact(int n);
int my_mod(int x, int y);

#endif // EXAMPLE_H

/* C/C++ file: example.c */
#include "example.h"

int fact(int n) {
    if (n < 0) return 0; /* Or handle error appropriately */
    if (n == 0) return 1;
    return n * fact(n - 1);
}

int my_mod(int x, int y) {
    if (y == 0) return 0; /* Or handle error appropriately */
    return x % y;
}

/* SWIG interface file: example.i */
%module example
%{
#define SWIG_FILE_WITH_INIT
#include "example.h"
%}

int fact(int n);
int my_mod(int x, int y);

# Build and run steps in bash
# 1. Generate SWIG wrapper code
# swig -python -c++ example.i

# 2. Compile C/C++ source and SWIG wrapper
# g++ -c example.c example_wrap.cxx -I/usr/include/python3.10 -fPIC

# 3. Link into a shared library
# g++ -shared example.o example_wrap.o -o _example.so

# Python usage:
import example

print(f"Factorial of 5: {example.fact(5)}")
print(f"7 mod 3: {example.my_mod(7, 3)}")