ctypesgen

library1.1.1pypypi✓ verified 86d ago

ctypesgen is a Python wrapper generator for `ctypes`, designed to automate the creation of Python bindings for C header files. It parses C/C++ header files and generates Python modules that use the `ctypes` foreign function interface to call functions and access data structures in shared C libraries. The current version is 1.1.1, with releases occurring periodically to address bugs and introduce new features, often yearly or bi-annually.

http-networking

pip install ctypesgen

github ↗package ↗

INSTALL

IMPORT

SIG · CTYPESGEN

ctypesgen

http-networkingpythonv1.1.1

Install

1.6s avg

Import

126ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.126s · 18.9MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.6s · import 0.125s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

main

✓ import ctypesgen.main

✗ import ctypesgen

The primary programmatic entry point is `ctypesgen.main.main()`, which takes a list of command-line arguments.

This quickstart demonstrates how to use `ctypesgen` programmatically to generate Python bindings for a simple C header file. It creates a dummy header, invokes `ctypesgen.main.main` with appropriate arguments to create a Python file, and then prints instructions for how to use the generated bindings (which requires compiling the C code into a shared library).

import os import ctypesgen.main # 1. Define your C header content header_content = """ // my_library.h #ifndef MY_LIBRARY_H #define MY_LIBRARY_H int add_numbers(int a, int b); void print_message(const char* msg); #endif """ # 2. Create a temporary header file header_file = "my_library.h" with open(header_file, "w") as f: f.write(header_content) # 3. Define the output Python bindings file output_file = "my_library_bindings.py" # 4. Run ctypesgen programmatically using its main function # Arguments are passed as a list of strings, just like command-line arguments. ctypesgen.main.main(["-o", output_file, header_file]) print(f"Successfully generated bindings to '{output_file}'") print("To use them, compile 'my_library.h' into a shared library (e.g., .so, .dylib, .dll),\n"+ "then import 'my_library_bindings' in Python and load the shared library.") # 5. Clean up temporary files os.remove(header_file)

ctypesgen --version

Debug

Known issues

breakingPython 2 support was completely dropped in version 1.1.0. Older projects relying on ctypesgen with Python 2 must remain on a pre-1.1.0 version or migrate to Python 3.

fix

Upgrade to Python 3.7+ or use ctypesgen<1.1.0 for Python 2 projects.

affects: >=1.1.0

gotcha`ctypesgen` relies on an underlying C compiler (like `gcc` or `clang`) being present in your system's PATH to parse C header files. If not found, it will fail to process headers.

fix

Ensure a C/C++ compiler is installed and accessible via your system's PATH. On Linux, install `build-essential`. On macOS, install Xcode Command Line Tools (`xcode-select --install`). On Windows, install MinGW or MSVC.

affects: All versions

gotchaWhen using `ctypesgen.main.main()` programmatically, arguments must be passed as a single list of strings, mimicking `sys.argv[1:]`. Passing them as separate arguments will result in a `TypeError`.

fix

Always pass arguments as a list: `ctypesgen.main.main(['-o', 'output.py', 'input.h'])`.

affects: All versions

gotchaBy default, `ctypesgen` embeds a preamble (library loader code) in each generated output file. For packaging or reducing duplication, use `--no-embed-preamble` to generate the preamble and loader into separate files.

fix

Add `--no-embed-preamble` to your ctypesgen arguments for separate preamble/loader files, then import them as needed.

affects: >=1.1.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'ply'

The `ply` package is a mandatory dependency for `ctypesgen` to parse C header files, but it was not installed.

fix

Install `ctypesgen` correctly using `pip install ctypesgen` or manually `pip install ply`.

FileNotFoundError: [Errno 2] No such file or directory: 'gcc'

ctypesgen uses an external C compiler (like `gcc` or `clang`) to preprocess and parse C header files. This error indicates that the compiler is not found in the system's PATH.

fix

Install a C/C++ compiler (e.g., `build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS, or MinGW/MSVC on Windows) and ensure it's added to your system's PATH.

TypeError: main() takes 1 positional argument but 2 were given

When calling `ctypesgen.main.main()`, command-line arguments are expected as a single list of strings, not separate arguments.

fix

Pass all arguments as a single list: `ctypesgen.main.main(['-o', 'output.py', 'input.h'])`.

Upgrade

Version history

1.1.1latest on PyPI · released Oct 19, 2022

Audit

Dependencies

plyrequiredUsed for parsing C header files (lexer/parser generator).

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ctypesgen/ctypesgen ↗

packagehttps://pypi.org/project/ctypesgen/ ↗