Metadata-Version: 2.4
Name: pyturbo-v3
Version: 3.0.6
Summary: PyTurbo V3 - Python to C99 transpiler for Windows
Author: Suleiman
Author-email: steal.apet@mail.ru
License: Apache-2.0
Keywords: python,c99,transpiler,compiler,cython,dce,windows,cpython,codegen,dll,upx
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: C
Classifier: Environment :: Console
Classifier: Environment :: Win32 (MS Windows)
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: System :: Software Distribution
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-python
Dynamic: summary

PyTurbo V3

Python 3.10 to C99 transpiler with CPython API and DCE.

Optimization method: all you can make to C99; the rest through CPython API.

Author: Suleiman
License: Apache 2.0
Copyright 2026 Suleiman


QUICK START

    pyturbo transpile hello.py -o hello.c -v

Output:

    hello.c              C99 + inline CPython declarations (~5 KB)
    hello.h              function prototypes
    hello.manifest.json  full analysis report

Compile with any C compiler:

    gcc -std=c99 hello.c -lpython3.11 -o hello
    ./hello

Or MinGW, clang, tcc, MSVC. Any of them works.


PLATFORM SUPPORT

    Windows 10 / 11 (64-bit)    full support, recommended
    Linux / macOS / Android     .c output only (no --min-dll)

PyTurbo V3 is designed and tested for Windows first.
The transpiler itself (analyzer, type inference, codegen, DCE)
is platform-independent and produces standard C99.
The --min-dll feature (isolated pythonXY.dll + UPX) is Windows-only,
because it relies on the PE format and Windows DLL loading rules.

On Linux / macOS / Android:
    - .c and .h output works
    - --min-dll is a no-op with a warning
    - link against system libpythonXY.so
    - example:
          gcc -shared -fPIC hello.c -lpython3.11 -o hello.so

To enable transpilation on non-Windows platforms, remove or relax
the platform guard in pyturbo.py:

    # was:
    if sys.platform != "win32":
        _fail_os()

    # now:
    if sys.platform != "win32":
        import warnings
        warnings.warn(
            "PyTurbo: --min-dll is Windows-only; .c output works everywhere"
        )

This is the only change required for .c output on Linux/macOS/Android.


FEATURES

C99 where possible:

    numbers                                -> double
    arithmetic                             -> native + - * /
    for i in range(n)                      -> for (double i = 0; i < n; i += 1)
    +=, -=, *=, ...                        -> native
    print(x, y)                            -> printf("%g %g\n", x, y)
    numeric function parameters            -> unboxed to double
    numeric return values                  -> boxed via PyFloat_FromDouble

CPython API fallback:

    strings, lists, tuples, dicts
    imports, module calls
    classes (via type())
    exceptions
    lambdas

DCE for Python.h:

    reads Python.h from the system
    extracts only the used prototypes (~15 of ~1800)
    inlines them into the .c file
    no #include <Python.h>
    no -I flag needed
    portable .c

DLL isolation on Windows with --min-dll:

    detects the running Python version (310, 311, 312, 313, ...)
    finds pythonXY.dll
    produces an isolated copy next to the .c file
    no Visual Studio required
    uses a pure-Python PE parser

Then:

    cd pyturbo_dist
    gcc hello.c -L. -lpython311 -o hello.exe

Or with MSVC, clang, tcc. Any of them.


COMMANDS

    pyturbo transpile <file.py> [-o out.c] [-v] [--min-dll] [--as-extension]
    pyturbo analyze   <file.py>
    pyturbo infer     <file.py>
    pyturbo tokens    <file.py>
    pyturbo version
    pyturbo help


EXAMPLE

    import math

    def sum_squares(n):
        total = 0
        for i in range(n):
            total += i * i
        return total

    def main():
        r = sum_squares(100)
        print("Result:", r)
        print("Sqrt:", math.sqrt(r))

    main()

Generated C (excerpt):

    PyObject* py_user_sum_squares(PyObject* py_n) {
        double py_n_v = PyFloat_AsDouble(py_n);
        double py_total = (double)((0L));
        for (double py_i = (double)((0));
             py_i < (double)(py_n_v);
             py_i += (double)((1))) {
            py_total += py_i * py_i;
        }
        return PyFloat_FromDouble(py_total);
    }

    PyObject* py_user_main(void) {
        PyObject* py_r = py_user_sum_squares(PyLong_FromLong(100L));
        double py_r_v = PyFloat_AsDouble(py_r);
        printf("Result: %g\n", py_r_v);

        PyObject* _m = PyImport_ImportModule("math");
        PyObject* _f = PyObject_GetAttrString(_m, "sqrt");
        PyObject* _t = PyObject_Vectorcall(_f, &py_r, 1, NULL);
        double _t_v = PyFloat_AsDouble(_t);
        printf("Sqrt: %g\n", _t_v);

        Py_INCREF(Py_None);
        return Py_None;
    }


C EXTENSIONS

PyTurbo output is already a valid C extension. It only lacks
the module boilerplate. You can add it manually, or (once
--as-extension is implemented) let PyTurbo emit it.

Manual boilerplate (~20 lines):

    static PyMethodDef module_methods[] = {
        {"sum_squares", py_user_sum_squares, METH_O, NULL},
        {"main",        py_user_main,        METH_NOARGS, NULL},
        {NULL, NULL, 0, NULL}
    };

    static struct PyModuleDef module_def = {
        PyModuleDef_HEAD_INIT,
        "hello",
        NULL,
        -1,
        module_methods
    };

    PyMODINIT_FUNC PyInit_hello(void) {
        return PyModule_Create(&module_def);
    }

Build as an extension:

    gcc -shared -fPIC hello.c -lpython3.11 -o hello.so
    # or on Windows:
    gcc -shared hello.c -L. -lpython311 -o hello.pyd

Import:

    python -c "import hello; hello.sum_squares(100)"

What this gives you:

    .c size        ~5 KB        (Cython: ~500 KB)
    .so size       ~50 KB       (Cython: ~1 MB)
    dependencies   0            (Cython: 3)
    Python.h       not needed   (Cython: #include <Python.h>)
    -I flag        not needed   (Cython: needed)
    build time     seconds      (Cython: minutes)
    input          .py          (Cython: .pyx)

Limitations compared to Cython:

    NumPy          not supported
    C++            not supported
    cdef class     not supported (classes are built at runtime)
    attribute specialization   not supported
    object-heavy speed          ~1x (Cython: 2-10x)
    ecosystem      none         (Cython: 18 years)

So: PyTurbo is a lightweight alternative to Cython for
small, numeric, pure-Python extensions - not a general
replacement.


SPEED

Realistic speedup range over CPython: 6x to 50x.

    50x     upper bound: fully numeric hot path
    6x      lower bound: mixed numeric + object code
    ~1x     object-heavy code (same as CPython)
    <1x     worst case: print(object) in loop, m.f(x) in loop

The 50x figure applies only to numeric code that fully passes
try_pure_c99. On object-heavy code PyTurbo emits generic
CPython API calls and may be slower than CPython due to
repeated ImportModule / GetAttrString.

This is not a bug; it is the boundary of the model:
"all you can to C99, the rest through CPython API".


SIZE COMPARISON

    feature                PyTurbo V3   Cython       Nuitka
    ---------------------  -----------  -----------  -----------
    input                  .py          .pyx         .py
    annotations            not needed   needed       not needed
    output                 .c           .c           .c / .exe
    .c size                ~5 KB        ~500 KB      ~1 MB
    binary                 ~50 KB       ~1 MB        ~5 MB
    dependencies           0 (CPython)  3            5
    Python.h               inlined      #include     #include
    DLL DCE (Windows)      copy + UPX   no           no
    works on Android       .c only      no           no
    speed (numeric)        ~50x         ~50x         ~1.3x
    speed (objects)        ~1x          2-10x        1.3x


PYTURBO VS CYTHON

Cython requires .pyx syntax with cdef, cpdef.
PyTurbo accepts pure Python and infers types automatically.

Cython:
    full plate armor: .pyx, cdef, cpdef
    broadsword: #include <Python.h> (~1800 prototypes)
    castle: ~3 MB package, 150,000 lines
    500 contributors
    18 years old

PyTurbo:
    t-shirt: pure .py
    scalpel: inline Python.h (~15 prototypes)
    laptop: 34 KB, ~3200 lines
    1 author
    brand new

Both produce fast C.
Both are peers in the same category.
Different eras, different styles.

Where PyTurbo wins:

    input is pure .py (no .pyx)
    .c is ~100x smaller
    no #include <Python.h>
    no -I flag
    0 dependencies
    build time: seconds
    Windows distribution with isolated UPX-compressed DLL
    .c output works on Linux / macOS / Android

Where Cython wins:

    NumPy integration
    C++ integration
    cdef class (real C types)
    attribute / method specialization
    object-heavy speed (2-10x)
    production ecosystem (18 years, 500 contributors)


PYTURBO VS NUITKA

Nuitka compiles for packaging (.exe).
PyTurbo focuses on generating minimal C with DCE.

Nuitka pulls in the full Python runtime.
PyTurbo removes unused declarations and inlines only the needed
~15 prototypes directly into the .c file.


DCE

Cython and Nuitka both require #include <Python.h> and pull
in all ~1800 prototypes.

PyTurbo removes unused declarations and inlines only the needed
~15 prototypes directly into the .c file.

On Windows with --min-dll, PyTurbo also isolates pythonXY.dll
next to the .c file, so the .exe loads our copy first
(Windows side-by-side rule).

No Visual Studio required.
Uses a pure-Python PE parser.

Note: the PE parser (pe_parser.py) is Windows-only by design.
It reads PE files, not ELF. It is not needed for .c output;
it is only used by --min-dll.


WHY PYTURBO

Not a new category.
A minimal implementation in an existing category.

Category: Python-to-C transpilers.
Peers: Cython, Nuitka.

PyTurbo is the best when you want:

    pure Python input, no annotations
    tiny .c (5 KB)
    no -I flag
    no #include <Python.h>
    0 dependencies
    small C extensions (~50 KB .so)
    minimal Windows distribution (isolated DLL + UPX)
    .c output on Linux / macOS / Android
    fast build cycle (seconds)

Cython is the best when you want:

    numpy integration
    C++ integration
    maximum speed with annotations
    cdef class
    production ecosystem

Nuitka is the best when you want:

    .exe packaging
    full Python compatibility
    no annotations needed


HONEST LIMITATIONS

    Windows is the primary platform.
        --min-dll, pe_parser.py, dll_decreaser.py, embed.py
        are Windows-only. The transpiler core is portable,
        but pyturbo.py currently blocks non-Windows at startup.
        Remove the platform guard to enable .c output elsewhere.

    No NumPy.
        PyTurbo does not understand ndarray, memoryview, or
        buffer protocols. numpy calls go through CPython API.

    No C++.
        PyTurbo emits C99 only.

    Classes are dynamic.
        class Foo: is built at runtime via PyType_Type.
        It is not a real C type.

    Object-heavy code is not faster.
        print(obj), m.f(x), obj.attr in loops may be slower
        than CPython due to repeated ImportModule / GetAttrString.

    Half of Python syntax is not implemented.
        Missing: with, try, raise, lambda, yield, await,
        decorators, f-strings, match. These are not C99
        limitations - they are unimplemented in codegen.py.

    DCE reads Python.h from the system.
        It is needed at transpile time, not at compile time.
        Without it, PyTurbo falls back to a hardcoded set
        of ~80 prototypes.

    --as-extension is not implemented yet.
        Output is a standalone .exe (with main()).
        To build a C extension, add the module boilerplate
        manually (see C EXTENSIONS section).


LICENSE

Apache License 2.0.
See LICENSE.txt.
