Skip to main content

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.

An f2py-style wrapper generator for C, with two additions:

  • one binary per platform for every Python (the nimpy trick: no libpython link, the CPython API is resolved at import);
  • CPU-architecture variants (SSE2/AVX2/AVX-512, NEON, Altivec) selected at run time.

The C it wraps looks like Fortran: scalars and flat arrays owned by the caller. No structs, strings, callbacks, keyword arguments or allocation. If you need those, or only target recent CPython, use something else instead. See docs/design.md.

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": [
                "b.n == a.n",
                "out.n >= a.n",
            ],
            "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 and the single-header runtime (c2py.h) next to it
c2py23 arraysum.c2py -o arraysum_wrapper.c --emit-header

# Compile  --  no libpython, no include path
cc -O2 -shared -fPIC arraysum_wrapper.c arraysum.c -ldl -lm -o arraysum.so

python3 -c "
import ctypes
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)()
arraysum.array_sum(a, b, r)
print(list(r))  # [6.0, 8.0, 10.0, 12.0]
"

The wrapper checks element type, alignment, contiguity and overlap of writable buffers on every call. It cannot know how far your C code reads or writes: every output buffer needs a size check in checks:. See "Writing Safe .c2py Definitions" in docs/user_guide.md.

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

Status

Beta. Built for the author's own production use (c2ImageD11, bslz4_to_sparse). Refuses to import on a Python newer than the last one audited (3.15). Tested on 2.7, 3.6-3.15, 3.14t and 3.15t; reviews and the crashes they found are in archive/.

License

MIT. See LICENSE.

Metadata

Release files for c2py23 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for c2py23 0.6.0
File Size Uploaded Provenance Actions
c2py23-0.6.0.tar.gz 198.3 kB Without provenance Details for c2py23-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for c2py23 0.6.0
File Interpreter ABI Platform Actions
c2py23-0.6.0-py3-none-any.whl Python 3 none any Details for c2py23-0.6.0-py3-none-any.whl

Total release size: 334.5 kB

Release files / c2py23-0.6.0.tar.gz

Download URL c2py23-0.6.0.tar.gz
Size 198.3 kB
Tags Source
SHA-256 checksum
How to use checksums
a1b5ae7e4b95b80318c14fd15f817e3a9e7e1c19bdcd9e94fd5074d516754e5a
BLAKE2b-256 checksum
How to use checksums
22e2e054200a9a68b102a252a2987891729d693ef608afad4e34499e9d69dca1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / c2py23-0.6.0-py3-none-any.whl

Download URL c2py23-0.6.0-py3-none-any.whl
Size 136.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bc21ab3d1e69b374451421268b9c958a3581a68a4f95b39df5951495895af4e7
BLAKE2b-256 checksum
How to use checksums
a5cef8a07e22fd481c30a1e403d07976661d8169411bac4bafddf156dbad4aef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for c2py23 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page