ctypesgen

Common errors

• ModuleNotFoundError: No module named 'ply'

  cause 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'

  cause 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

  cause 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'])`.

Warnings

• breaking Python 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.
• 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.
• gotcha When 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'])`.
• gotcha By 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.

Install

• pip install ctypesgen Install ctypesgen

Imports

• main
  wrong:

  import ctypesgen

  correct:

  import ctypesgen.main

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

Quickstart

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)