-
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
AutoPxd
Several tools exist to parse header files and automatically produce Cython bindings.
| Tool | Status | Last Update (as of Dec 2025) |
|---|---|---|
| autowrap | ✅ Active | v0.24.0 (2025) |
| python-autopxd2 | ✅ Active | v3.2.1 (2025) |
| cwrap | ❌ Dead | 8163ff2 (2019) |
| xdress | ❌ Dead | eb7f0a0 (2014) |
| cython-codegen | ❌ Dead | b1856d3 (2011) |
| fwrap | ❌ Dead | f2e20eb (2010) |
| pxd-gcc-generation | ❌ Dead | ba5c5ff (2012) |
| Step | autowrap | python-autopxd2 |
|---|---|---|
| Input required | Hand-written .pxd | C/C++ header (unmodified) |
| Parse C/C++ header | ❌ Manual | ✅ Automatic |
| Generate .pxd declarations | ❌ Manual | ✅ Automatic |
| Generate .pyx wrappers | ✅ Automatic | ❌ Not generated |
| Generate cimport statements | ❌ Manual | ✅ Automatic |
| System include detection | ❌ Manual -I flags | ✅ Automatic |
| Recursive includes | N/A | ✅ Automatic |
| Python↔C++ type conversion | ✅ Automatic (runtime) | ❌ Not applicable |
| Manual files to write | .pxd + setup.py | None |
- You want to quickly generate .pxd files from existing headers
- You don't want to write any Cython declarations by hand
- You need to wrap a large C/C++ API with minimal effort
- You want recursive processing of umbrella headers that include other headers
autopxd mylib.h mylib.pxdInput: Unmodified C/C++ header Output: C/C++ <-> Cython interface (.pxd file) Manual work: Write Cython <-> Python interface (.pyx file)
- You need fine-grained control over Python-to-C++ type conversion
- You want automatic .pyx generation with Python special methods
- You need custom exception handling or operator overloads
- You're willing to manually write .pxd declarations with annotations
autowrap --out py_mylib.pyx mylib.pxd
Input: C/C++ <-> Cython interface (.pxd file with special comment annotations) Output: Cython <-> Python interface (.pyx file ready to compile as an extension) Manual work: Write C/C++ <-> Cython interface (.pxd file)
- Generate .pxd file with autopxd
autopxd mylib.h mylib.pxd
- Manually annotate mylib.pxd for autowrap consumption
- Generate .pyx file with autowrap
autowrap --out mylib.pyx mylib.pxd
- Integrate .pyx file into your package build process
| Tool | C | C++ | Fortran | Parser Backend |
|---|---|---|---|---|
| autowrap | ✅ | ✅ | ❌ | Cython parser (reads .pxd) |
| python-autopxd2 | ✅ | ✅ | ❌ | libclang / pycparser |
| cwrap | ✅ | ❌ | libclang / gcc_xml | |
| xdress | ✅ | ✅ | ❌ | libclang / pycparser |
| cython-codegen | ✅ | ❓ | ❌ | gcc_xml |
| fwrap | ❌ | ❌ | ✅ | Custom Fortran parser |
| pxd-gcc-generation | ✅ | ✅ | ❌ | GCC plugin |
| Feature | autowrap | python-autopxd2 |
|---|---|---|
| Classes | ✅ | ✅ |
| Templates | ✅ | ✅ |
| Namespaces | ✅ | ✅ |
| Enums | ✅ | ✅ |
| Static methods | ✅ | ✅ |
| Macro extraction | ❌ | ✅ |
| Forward declarations | ❌ | ✅ |
| Exception conversion | ✅ | ❌ |
| Operator overloads | ✅ | ✅ |
| Python special methods | ✅ (hash, etc.) | ❌ |
| Custom type converters | ✅ | ❌ |
| Manual code injection | ✅ | ❌ |
| Docker image | ❌ | ✅ |
(Potential pipeline: header → autopxd2 → .pxd → add annotations → autowrap → .pyx)
- Original: https://github.com/enthought/cwrap (gcc_xml, 2011)
- Fork: https://github.com/geggo/cwrap (libclang, ~2021)
- C++ support noted as "rudimentary" with known issues
https://github.com/xdress/xdress Last release over a decade ago. 72 open issues, 13 open PRs.
https://github.com/cournape/cython-codegen Author states: "YOU SHOULD CONSIDER IT UNSUPPORTED" and recommends clang-based tools.
https://github.com/kwmsmith/fwrap Beta software from ~2011. Requires Python 2.5-2.6.
https://github.com/robertwb/cython/tree/pxd-gcc-generation Philip Herron's 2012 GSoC project. Requires gcc-python-plugin.
Script by Evan Buswell. Status unknown. http://groups.google.com/group/cython-users/browse_thread/thread/67c3c4443a9c98ca