ctypeslib2

To use ctypeslib2, you must first install the LLVM Clang library on your system, followed by the ctypeslib2 Python package and the clang Python bindings. It is critical that the version of the clang Python package matches the version of the LLVM Clang library installed on your system.

1. Install LLVM Clang

Linux (APT):

$ sudo apt install libclang1-19

Using LLVM install script:

$ wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh
$ ./llvm.sh 19

macOS: Install Xcode Command Line Tools:

$ xcode-select --install

2. Install Python Packages

Install ctypeslib2 and the corresponding clang package via pip. Ensure the version numbers match your installed LLVM version.

macOS specific command (for Clang 15):

% pip install ctypeslib2 'clang>=15,<16'

# Example for Clang 16
pip install ctypeslib2 clang==16

The clang2py CLI tool generates Python-friendly interfaces to C libraries by converting Clang headers into ctypes definitions. It can automatically generate Python classes representing C data structures and simplify wrapping C functions.

Basic Usage

clang2py [options] <source_filenames>

If no output filename is specified via -o, the generated code is sent to standard output (stdout). You can also provide - as a filename to explicitly use stdout.

Key CLI Options

Generation Control

• -c, --comments: Include source Doxygen-style comments in the output.
• -d, --doc: Include docstrings containing the C prototype and source file location.
• -e, --show-definition-location: Include the source file location in comments.
• -k, --kind <TYPEKIND>: Specify which type descriptions to include.
  • Valid characters: a (Alias), c (Class), d (Variable), e (Enumeration), f (Function), m (Macro), s (Structure), t (Typedef), u (Union).
  • Default: cdefstu.
• -i, --includes: Include declarations defined outside of the provided source files.
• -x, --exclude-includes: Parse objects in source files only; ignore includes.

Symbol and Library Filtering

• -s, --symbol <SYMBOL>: Include only specific symbols. If no symbols or regexes are provided, everything is included.
• -r, --regex <EXPRESSION>: Include symbols matching the provided regular expression.
• -l, --include-library <DLL>: Specify a library to search for exported functions. This can be used multiple times.
• -w: Add all standard Windows DLLs to the searched DLL list.
• -m, --module <module>: Specify Python modules containing symbols that should be imported instead of being generated.
• --preload <DLL>: Specify a DLL to be loaded before all others to resolve symbols.
• --nm <program>: The nm program to use for extracting symbols from libraries (defaults to nm).

Configuration and Debugging

• -o, --output <filename>: Specify the output filename (defaults to - for stdout).
• --clang-args="<args>": Pass raw arguments directly to Clang (e.g., --clang-args="-std=c99 -Wall").
• -t, --target <target>: Set the target architecture (e.g., --target x86_64).
• --debug: Set logging level to DEBUG.
• -q, --quiet: Shut down warnings and below.
• -v, --verbose: Enable verbose output.
• --max-depth <N>: Limit cursor expansion to depth N.
• --show-ids: Do not compute cursor IDs (improves speed but may limit functionality).
• --validate <bool>: Validate the generated Python code (defaults to True).

Input/Output

• Input Files: Provide one or more source filenames. Use - to read from stdin.
• Output: Use -o <file> to save to a file, or omit to use stdout.

# Example: Generate Python code from a header, including docstrings and comments, saving to a file
clang2py -c -d -o my_library.py my_header.h

# Example: Generate code for specific symbols using a regex and passing clang flags
clang2py -r "^api_" --clang-args="-I/usr/include/custom" my_header.h

You can use ctypeslib directly in your Python code to translate C strings or files into Python modules using ctypes structures.

Translate C strings

Use ctypeslib.translate() to convert a C code snippet into a Python object.

Translate C files

Use ctypeslib.translate_files() to convert one or more .c files. You can specify an outfile to write the result to a file or use cfg (a CodegenConfig object) to pass custom Clang arguments for cross-platform translation.

import ctypeslib
from ctypeslib.codegen import config

# 1. Simple translation
py_module = ctypeslib.translate('''int i = 12;''')
print(py_module.i)

# 2. Translate files to a specific output file
ctypeslib.translate_files(['mytest.c'], outfile=open('mytest.py', 'w'))

# 3. Translate with custom Clang arguments (e.g., for cross-compilation)
cfg = config.CodegenConfig()
cfg.clang_opts.extend(['-target', 'arm-gnu-linux'])
py_module = ctypeslib.translate_files(['mytest.c'], cfg=cfg)

import ctypeslib

# Translate a string
py_module = ctypeslib.translate('''
struct coordinates { int i; int y; };
''')

# Access the generated structure
coords = py_module.struct_coordinates(1, 2)
print(coords.i, coords.y)

The clang2py command-line tool generates Python code from C header or source files. It is useful for batch processing or quick conversions.

Basic Usage

clang2py my_header.h

Common CLI Flags

• -o OUTPUT: Specify the output filename (defaults to stdout).
• --clang-args CLANG_ARGS: Pass raw arguments to Clang (e.g., --clang-args="-I/usr/include/clang/4.0/include").
• -t TARGET: Specify the target architecture (e.g., -t x86_64-Linux).
• -s SYMBOL: Include only specific symbols.
• -r EXPRESSION: Use a regex to include specific symbols.
• -k TYPEKIND: Filter which type descriptions to include (e.g., s for Structures, f for Functions).

Cross-Architecture Translation

To generate code for a different architecture, use the --clang-args flag to pass the -target option to Clang:

clang2py --clang-args="-target x86_64" my_file.c

# Example: Generate python code from a C file with specific include paths
clang2py --clang-args="-I/usr/include/clang/4.0/include" test-stdbool.c