How PythonC Turns Typed Python into Standalone C Programs

PythonC is a new Python‑to‑C code generator that goes beyond Cython by allowing developers to write Python with type hints and compile it into C code, producing either C extensions or fully independent C executables.

Basic PythonC program

A simple example demonstrates the @compile decorator to mark functions for compilation and the use of the i32 type for machine‑native integers:

from pythoc import compile, i32
@compile
def add(x: i32, y: i32) -> i32:
    return x + y
if __name__ == "__main__":
    print(add(10, 20))

Only functions decorated with @compile are compiled, and the generated C code is compiled on each run, causing a short delay.

Generating a standalone C executable

By adding a main function and calling compile_to_executable(), the module is compiled into a named executable placed in a build directory:

from pythoc import compile, i32, ptr, i8
from pythoc.libc.stdio import printf
@compile
def add(x: i32, y: i32) -> i32:
    return x + y
@compile
def main(argc: i32, argv: ptr[ptr[i8]]) -> i32:
    printf("%u
", add(10, 20))
if __name__ == "__main__":
    from pythoc import compile_to_executable
    compile_to_executable()

The resulting executable behaves like a hand‑written C program, with the entry point matching the main function name.

Simulating C language features

PythonC supports pointer types ( ptr[T]), fixed‑size arrays ( array[T, N]), and can model structs, unions, and enums via class decorations. Control‑flow constructs such as goto are not supported, but match/case can be used via __include__. Variable‑length arrays are currently unavailable because they require C11 support.

Compile‑time code generation

Unlike Cython, PythonC can generate different C code paths at compile time. An example shows a generic make_point function that, given a type like i32 or f64, creates a specialized Point struct and an add_points function:

from pythoc import compile, struct, i32, f64
def make_point(T):
    @struct(suffix=T)
    class Point:
        x: T
        y: T
    @compile(suffix=T)
    def add_points(p1: Point, p2: Point) -> Point:
        result = Point()
        result.x = p1.x + p2.x
        result.y = p1.y + p2.y
        return result
    return Point, add_points
Point_i32, add_i32 = make_point(i32)
Point_f64, add_f64 = make_point(f64)

The @type suffix adds the type name to generated symbols, enabling C‑style function overloading.

Memory‑safety features

PythonC introduces linear types to enforce safe manual memory management. A linear proof object must be consumed when freeing memory, preventing mismatched allocations. Functions like lmalloc() and lfree() replace traditional malloc() / free() calls, moving many checks to compile time.

Refinement types via refine() allow developers to attach checks (e.g., non‑null pointers) to values, ensuring the compiler verifies that such checks are performed before the value is used.

Future directions

PythonC is still early‑stage. Planned enhancements include tighter runtime integration with Python, such as an @cached decorator that pre‑compiles a module once and reuses the compiled binary on subsequent imports, potentially integrating with Python's existing build systems.

Overall, PythonC offers a powerful alternative for developers needing fine‑grained control over generated C code while retaining Python’s expressive syntax.