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 1.0.1 package release contract over the Phase 16 converter base plus authenticated 1.0.1 set rules. Candidate distributions are published to PyPI only after the complete local release review revalidates the source, distributions, required PySide6 desktop application, and immutable assets.

The complete programmer's conversion reference is built into the installed application. Choose Help → PyCForge Help… or press F1 for 14 classified, searchable, offline HTML pages with persistent left navigation. Maintainers can edit or add pages under pycforge/ide/resources/help/; HELP.md documents the catalog and packaging contract. The archived PyCForge 0.16.0 Programmer's Conversion Guide is retained for converter-contract custody; F1 Help is the current user reference.

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

Install a downloaded source package on Windows 11

Open PowerShell in the folder containing pycforge-1.0.1.tar.gz. Use the Python Launcher to create a dedicated environment and install the archive directly:

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install --no-cache-dir .\pycforge-1.0.1.tar.gz

Verify the package and command, then launch the workspace:

.\.venv\Scripts\python.exe -c "import pycforge; print(pycforge.__version__)"
.\.venv\Scripts\pycforge.exe --help
.\.venv\Scripts\pycforge-workspace.exe

For source review, extract the archive, open PowerShell in the extracted pycforge-1.0.1 directory, and replace the final install argument with .. Keep the original archive unchanged so its checksum remains a useful custody record.

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

With the Windows Python Launcher, the same entry point is:

py -m pycforge.ide

At launch, a branded startup progress dialog reports four real initialization stages: vector-resource validation, offline Help validation, authentication and Compact-IR parsing of every packaged Ting agent, and workspace construction. It uses no artificial timer and makes no network request. A corrupt or missing resource remains visible as a precise startup failure instead of opening a partially initialized workspace.

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. A new workspace is genuinely empty; the first opened or created module becomes primary automatically, and every tab—including the first and final one—can be closed without recreating a mandatory placeholder.
• Python-only function folding from a larger gutter marker, direct Edit menu actions, or Fold All/Unfold All header controls, with low-contrast indent guides that never appear in generated C. Large-source fold discovery reuses the authenticated background structure observer, so Fold All never runs a full parser on the UI thread.
• Independent persisted code sizing from Code & Editor Settings…: Python source defaults to 14 pt and generated C to 12 pt, each within an 8–48 pt range. Direct increase, decrease, and reset shortcuts affect Python only; ForgeLens remains independently configurable.
• Ordinary non-editor controls conform to the reviewed menu font: a 12 pt minimum that respects larger Windows accessibility choices. The three workspace caption bands use a deliberate compact 10 pt hierarchy to return editor height; Python-header identity fields elide responsively while their complete values remain available. Help article text retains its independent 12–14 pt reading hierarchy, and screen-aware sizing keeps restored windows inside the current monitor work area.
• Motionless editing chrome: normal typing updates state in place without replacing the lower-left status message, blinking state 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, title text that elides before the minimize/maximize/close controls, 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. Find/Replace keeps Previous and Next together when the replacement row is visible.
• Exact, passive ForgeLens Python↔C cross-highlighting and flat dark Open/Save browsers; Open renders menu-sized monospaced source pages with compact line spacing in memory, while Save stays preview-free. Dialog geometry, columns, location, splitter, and the visibly selected preview file are remembered.
• Linked Python files that remain open at exit and their active tab restore in prior order. Missing or unreadable paths are reported individually; unsaved buffers are not persisted. Closing the final tab persists an intentionally empty restart. Clear Recent Files clears only convenience history and cannot close current tabs, delete files, or change the restart session.
• Accepted Python and generated-C text sizes are synchronously mirrored as durable editor preferences so a presentation-schema cleanup cannot reset a user's chosen code size on restart.
• Every dialog uses flat custom PyCForge chrome with an extensible titlebar tool slot; resizable dialogs provide custom maximize/restore and resize targets.
• A classified 14-page offline HTML Help system with global search, persistent left navigation, a dedicated Help menu, and editable catalogued sources.
• Undo, Redo, Cut, Copy, and Paste on the main toolbar.
• 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.
• Version 1.0.1 fixed local sets for unique homogeneous integer, finite-float, or Boolean literals, with once-evaluated bounded in/not in membership.
• Six deterministic Ting reasoning agents for conversion engineering: five mandatory proof roles plus typed capability/resource binding, with editable tested RuleSpecs, verified Compact-IR, appendable roles, indexed matching, and finite per-agent execution budgets.

Ting conversion engineering

PyCForge privately namespaces an execution-only extraction of the reviewed Ting Reasoner 0.1.0a21 runtime. The public package includes the bounded Compact-IR loader/parser and verifier required to authenticate, decode, materialize, and execute precompiled .ting files. It excludes only the authoring-side RuleSpec source parser, Compact-IR compiler, artifact writer, builder command, console, and standalone Ting entry point. Five core agents independently review syntax, semantics, ownership, lowering, and verification evidence. A sixth shipped agent binds registered providers and symbolic runtime strategies to signed-64 resource ceilings. The registry can append further precompiled agent roles and discover typed Boolean, integer, and bounded-symbol evidence without coordinator changes.

Run the complete embedded rulepack gate from an extracted source package:

python -m tools.validate_ting_agents

This gate is read-only, executes every embedded test, and has no write or test-skip switch. Editable .tingspec.json review sources are present in the source archive but omitted from the installed wheel. Compilation happens only with a separately retained, hash-verified Ting compiler custody package; that compiler is never included in a PyCForge distribution. PyCForge 1.0.1 fixes this subsystem to shadow mode: its decisions are deterministic engineering evidence and cannot yet alter or authorize generated C. See specifications/ting_agent_architecture.md for the promotion and extension protocol.

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 including the documented set-membership profile, 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. Open the built-in searchable Help before adopting PyCForge for production input; it is the complete installed conversion reference.

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.

• Version 1.0.1 admits one directly assigned local set containing 1–64 unique, homogeneous direct int, finite float, or bool literals. A matching expression may use in or not in against that local name. The expression is evaluated once and lowered to a bounded equality chain over read-only automatic C storage. Empty, duplicate, heterogeneous, computed, or string elements; comprehensions; indexing; iteration; mutation; methods; aliases; rebinding; passing; returning; and escape all reject with coded diagnostics.

  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 Help → PyCForge Help… → Safety and limits for the complete product boundary and caller responsibilities.

Documentation

• Primary user documentation: launch the workspace and press F1. The packaged HTML covers every active conversion, accepted and rejected shapes, workspace operation, file status/ownership rule, CLI/API use, diagnostic family, resource ceiling, shortcut, and contract identity.
• Current Help dialog screenshot
• Archived 0.16.0 Programmer's Conversion Guide
• EXPERT_REVIEW_1.0.1.md — release findings and upload disposition.
• CONVERSION_ROADMAP.md — prioritized professional conversion expansion.
• PYPI_RELEASE.md — Windows 11 source-install and PyPI release gate.
• The source distribution also carries README.md, RELEASE_NOTES.md, CHANGELOG.md, CURRENT_STATE.md, and LICENSE.

Development

From an unpacked PyPI source distribution:

python -m venv .venv
python -m pip install --upgrade pip
python -m pip install -e .
python -m pip install pytest==9.1.1 reportlab==4.4.9 pypdf==6.10.0 build twine "readme-renderer[md]==45.0" ruff==0.16.7 setuptools==82.0.1
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. The complete license text is included as LICENSE.