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 buffersexamples/lz4_wrap/-- compress/decompress over byte buffersexamples/simd_dispatch/-- CPU feature dispatch (SSE2/AVX2/AVX-512, NEON, Altivec)examples/threading_bench/-- GIL release, free-threading, OpenMPexamples/wheel_demo/-- multi-platform wheel packagingexamples/cmake_demo/,examples/meson_demo/-- build system integration
Documentation
- c2py23 docs -- user guide, spec, examples, developer guide
docs/specification.md-- full.c2pygrammar, supported types, architecturedocs/user_guide.md-- thread safety, wheel packaging, GIL release, timingdocs/getting_started.md-- installation and first builddocs/developer_guide.md-- testing with snakepit containers, CI, ABI matrixAGENTS.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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.