c2py23

All code in this repository was generated by DeepSeek V4 and other large language models, in collaboration with jonwright.

Wrap C99 functions as Python C extensions via the buffer protocol. One compiled .so works on Python 2.7 through 3.15 with no recompilation. Zero copies, zero allocations. No numpy required.

Install

pip install c2py23

Requires a C99 compiler (gcc, clang, or MSVC on Windows). No Python dependencies beyond stdlib.

Quick Start

Create a C function:

/* arraysum.c */
#include <stdint.h>
int array_sum(const double *a, const double *b, double *out, intptr_t n) {
    for (intptr_t i = 0; i < n; i++) out[i] = a[i] + b[i];
    return n;
}

Write the interface file:

# arraysum.c2py
{
    "module": "arraysum",
    "source": ["arraysum.c"],
    "functions": [
        {
            "py_sig": "array_sum(a: buffer, b: buffer, out: buffer) -> int",
            "checks": [
                "a.format == 'd'",
                "b.format == 'd'",
                "out.format == 'd'",
            ],
            "c_overloads": [
                {
                    "sig": "array_sum(const double *a, const double *b, double *out, intptr_t n) -> int",
                    "map": {
                        "a": "a.ptr",
                        "b": "b.ptr",
                        "out": "out.ptr",
                        "n": "a.n",
                    },
                },
            ],
        },
    ],
}

Build and use:

# Generate the wrapper
c2py23 arraysum.c2py -o arraysum_wrapper.c

# Compile (dlsym mode  --  portable, no libpython)
cc -shared -fPIC -I c2py23/runtime/ arraysum_wrapper.c arraysum.c \
   c2py23/runtime/c2py_runtime.c -ldl -lm -o arraysum.so

# Or build via setuptools
python setup.py build_ext --inplace

python3 -c "
import ctypes, sys; sys.path.insert(0, '.')
import arraysum
a = (ctypes.c_double * 4)(1, 2, 3, 4)
b = (ctypes.c_double * 4)(5, 6, 7, 8)
r = (ctypes.c_double * 4)(0, 0, 0, 0)
arraysum.array_sum(a, b, r)
print(list(r))  # [6.0, 8.0, 10.0, 12.0]
"

Usage

c2py23 file.c2py -o wrapper.c       # generate C wrapper
c2py23 file.c2py                     # print to stdout
c2py23 --version                     # print version
c2py23 file.c2py -o wrapper.c --emit-header       # also emit c2py.h alongside the wrapper
c2py23 --regenerate-header                        # regenerate c2py.h from runtime sources

# Or via python -m:
python -m c2py23 file.c2py -o wrapper.c

See c2py23/setuptools_helper.py for PythonhBuildExt setuptools helper (pythonh mode only).

Supported Platforms

Linux (x86_64, aarch64, gcc/clang/tcc/zig), macOS (aarch64, clang), Windows (x64/i386, MSVC/MinGW). Free-threaded Python 3.13+ supported.

Examples

The GitHub repository includes build examples (not in the PyPI sdist):

• examples/kissfft_wrap/ -- real + complex FFT over float buffers
• examples/lz4_wrap/ -- compress/decompress over byte buffers
• examples/simd_dispatch/ -- CPU feature dispatch (SSE2/AVX2/AVX-512, NEON, Altivec)
• examples/threading_bench/ -- GIL release, free-threading, OpenMP
• examples/wheel_demo/ -- multi-platform wheel packaging
• examples/cmake_demo/, examples/meson_demo/ -- build system integration

Documentation

• c2py23 docs -- user guide, spec, examples, developer guide
• docs/specification.md -- full .c2py grammar, supported types, architecture
• docs/user_guide.md -- thread safety, wheel packaging, GIL release, timing
• docs/getting_started.md -- installation and first build
• docs/developer_guide.md -- testing with snakepit containers, CI, ABI matrix
• AGENTS.md -- contributor guidelines for LLM agents

License

MIT. See LICENSE.