PyCForge

PyCForge is a deterministic Python-to-C source transpiler with a full PySide6 (Qt 6) desktop workspace, a command-line interface, and a Python API. It converts a documented, deliberately bounded Python subset into readable C11 source while producing diagnostics, source mappings, decision traces, and reproducible fingerprints.

This source tree defines the PyCForge 0.16.2 package release contract over the unchanged 0.16.0 converter contracts. Tagged builds are published only after the complete release workflow revalidates the source, distributions, required PySide6 desktop application, and immutable assets.

Open the 35-page PyCForge 0.16.0 Programmer's Conversion Guide (PDF)

Quick start

PyCForge requires Python 3.11 or newer. For a fresh install on macOS or Linux:

python -m pip install pycforge

On Windows, use the Python Launcher:

py -m pip install pycforge

A plain install does not replace an already-installed satisfactory version. Upgrade an existing installation explicitly:

python -m pip install --upgrade pycforge

py -m pip install --upgrade pycforge

Each install or upgrade includes PySide6 and the desktop application as required dependencies. There is no GUI extra and no separate desktop package. Minimal Debian/Ubuntu installations must also provide the system EGL runtime (sudo apt-get install libegl1); the pinned Linux CI and release runners install it explicitly before exercising real Qt widgets.

Launch the desktop workspace:

pycforge-workspace

The equivalent module command is:

python -m pycforge.ide

A 60-second conversion

Save this as example.py:

def add(left: int, right: int) -> int:
    return left + right

Convert it:

pycforge convert example.py --output example.c

PyCForge produces:

#include <stdint.h>

int64_t add(int64_t left, int64_t right);

int64_t add(int64_t left, int64_t right)
{
    return left + right;
}

The generated C is deterministic for the same authenticated source bundle and converter configuration.

What PyCForge provides

• A Python-first PySide6/Qt 6 workspace with document tabs, source splitting, navigation, search, outline, command palette, and conversion history.
• Persisted 8–48 pt Python-editor text sizing from Edit → Editor Settings… that survives restart and stays synchronized across split source panes, with a default-on ForgeLens toggle and undoable Python-aware auto-indentation.
• Motionless editing chrome: normal typing updates state in place without blinking status labels, source breadcrumbs, or toolbar controls; progress animation appears only while a conversion is actually running.
• A compact frameless, menu-preserving shell with shorter toolbars and notices, dark-theme module trees and navigation, bounded file-browser sizing, and a wider categorized About view without personal identity text and with clear conversion-boundary and workspace-state cues.
• Exact, passive ForgeLens Python↔C cross-highlighting and custom blackened-steel Open/Save browsers; Open renders readable source pages in memory, while Save stays preview-free.
• Explicit source bundles containing 1 to 64 Python documents, including bounded cross-module function imports.
• Read-only generated C with clean text presentation plus source mappings, overview-rail navigation, diagnostics, conversion summary, decision trace, and telemetry inspectors.
• Isolated, cancellable desktop conversion so the converter does not run on the GUI thread.
• A headless CLI for scripts and build pipelines.
• A Python API for applications that need structured conversion results.
• Stable diagnostics and fail-closed rejection of unsupported Python.
• Exact virtual-EOF mapping for valid source without a terminal newline, so conversion does not require or silently insert an empty final line.
• Phase 16 proofs for selected branch-defined scalar locals, Python loop completion (while/for ... else), overflow-safe signed-64 range updates, and one closed bounded UTF-8 file read/write profile.

Command-line interface

Write generated C to a file:

pycforge convert input.py --output generated.c

Emit the structured result as JSON:

pycforge --format json convert input.py

See all commands and options:

pycforge --help

Python API

from pycforge import ConversionRequest, PythonToCConverter

source = """\
def add(left: int, right: int) -> int:
    return left + right
"""

result = PythonToCConverter().convert(
    ConversionRequest.from_source(source)
)

if result.generated_c is not None:
    print(result.generated_c)
else:
    for diagnostic in result.diagnostics:
        print(diagnostic)

The desktop workspace, CLI, and Python API use the same converter and result contracts.

Supported Python

PyCForge is intentionally not a general Python runtime. Its current subset includes strictly annotated top-level functions using selected scalar values, arithmetic and comparisons, if/elif/else, bounded while and range loops including proved loop else, direct eligible function calls, fixed homogeneous containers, a bounded static-record profile, selective scalar scope hoisting, and exact bounded UTF-8 file sessions.

Anything outside the documented subset is unsupported by default and is rejected with diagnostics rather than silently approximated. Read the exact supported-Python specification before adopting PyCForge for production input.

Phase 16 in brief

• A scalar local first assigned below an exhaustive if can be declared once at C function entry when every reachable use is definitely preceded by a compatible int, float, bool, or str store. This is selective proof, not general Python scope or closure support.

• else is supported on admitted while, positional range, and fixed list/tuple/dictionary loops. Natural termination—including zero iterations—runs the else suite; only a break owned by that exact loop suppresses it. Nested breaks, continue, and returns retain Python control ownership. Phase 16 also guards a signed-64 range update before adding its step, avoiding C signed overflow at the exhaustion boundary.

• File I/O is limited to a direct one-item with open(path, 'r' or 'w', encoding='utf-8', newline='') as handle inside a top-level function, with one direct read() transfer or one write(text) statement whose text is an already-proved string name or string literal. Effectful write expressions are rejected because helper-internal open cannot preserve context-entry ordering. An assigned read result must declare a fresh direct local rather than rebind a parameter or earlier local. Reads are bounded (1 MiB by default, 16 MiB hard maximum), validate UTF-8 and reject embedded NUL, and transfer one unique buffer only after close succeeds. Writes use borrowed UTF-8 text, require an exact byte count, and propagate close failure. Aliasing, rebinding, explicit close, arbitrary modes, multiple context items, and general file-object behavior fail closed.

  At the generated-C ABI, the external caller must supply non-null, NUL-terminated valid UTF-8 path strings. Borrowed write text has the same preconditions and must contain no embedded NUL. The helpers cannot independently validate pointer validity, path UTF-8/NUL properties, or an embedded NUL beyond the first terminator in write text. Source path literals containing NUL reject with PYC3903; write literals containing NUL reject with PYC3905. Runtime codes 5 and 6 describe read file content only.

Safety boundary

PyCForge parses supplied source as data. Conversion never imports or executes the input Python, scans the host environment for modules, resolves undeclared files, or opens a path selected by the source program. It stops after C source generation. PyCForge never compiles, assembles, links, loads, runs, or executes the generated C.

Generated C for an admitted Phase 16 file-effect function performs file I/O only if someone separately builds and runs that C outside PyCForge. Its public C entry point has one generated final int64_t * status parameter; the external caller owns that writable status storage and must pass a non-null pointer. Each file-effect entry initializes it to success immediately after the null guard and before source-controlled work; helpers overwrite it on failure. A successful read returns a unique malloc-owned char *; the external caller owns it and must release it with free. Failures return null for reads or the function's failure value for writes and publish the stable status code. Source-defined calls to file-effect functions are rejected in the initial profile so this ABI cannot be bypassed inside transpiled Python.

Python int values map to the documented signed 64-bit representation domain; other supported Python values likewise follow explicit target-C contracts. Review the product boundary and the Programmer's Conversion Guide for the complete limitations.

Documentation

• Programmer's Conversion Guide - 0.16.0 Reference Edition (PDF)
• Supported Python
• Workspace specification
• UI roadmap
• Current state
• Release notes
• Changelog
• Security policy

Development

git clone https://github.com/lastforkbender/pycforge.git
cd pycforge
python -m venv .venv
python -m pip install --upgrade pip
python -m pip install -e .
python -m pip install pytest reportlab==4.4.9 pypdf==6.10.0
QT_QPA_PLATFORM=offscreen python -m pytest -q -rs

The normal editable installation includes PySide6, matching the package users receive from PyPI. Automated release checks cover Python 3.11 and 3.12 on Linux with real PySide6 widgets using Qt's offscreen platform.

License

PyCForge is free software released under the GNU General Public License v3.0 only.