PyCForge v1.3.57

PyCForge is a Python-to-C source transpiler and PySide6 desktop IDE. Edit Python, convert supported programs into readable C11, inspect the generated code, and compile with an optional native C toolchain—all from one workspace. A command-line interface and Python API bring the same conversion capabilities to scripts and other development tools.

Choose Typed conversion for annotated functions and direct C interfaces, or Runtime conversion for richer Python data and behavior: Unicode text, mutable containers, classes with single or multiple inheritance, decorated functions, closures, comprehensions, and file-processing programs spread across multiple source files.

A workspace for Python and C

• Edit comfortably: tabbed Python documents, split views, function folding, an outline, multiple cursors, and a command palette.
• Check Python code: use the wrench menu to scan current editor text. Python analysis and four Ting agents check supported module/function paths, helper arguments and returns, local calls, and mutable defaults. Optional open-module tracing follows supplied imports. Click a finding to reach its code; results remain until re-scan, and Cancel clears the panels.
• Quick conversion diagnostics: an amber warning-triangle button beside Tools opens the current failed conversion’s one-line diagnostics. Click a row to highlight its source; editing immediately disables outdated navigation.
• See the translation: side-by-side Python and read-only C, source diagnostics, conversion details, history, and searchable output. ForgeLens connects mapped Python and C locations in Typed and Runtime modes.
• Work across files: supply up to 64 Python modules, keep their source together, and generate C from the selected primary document and its supplied dependencies.
• Keep a project together: save open Python modules in a portable .pcfproj bundle, preview it before opening, and compare or restore named checkpoints.
• Stay in control: cancel background conversions, see when edits make generated output stale, and choose where to save the C result.
• Make the workspace yours: saved layouts, independent Python and C text sizes, keyboard commands, and 30 searchable offline Help pages.
• Build from the IDE: select PCFC11, GCC/MinGW-w64, Clang/Apple Clang, MSVC, or Clang-cl and create object files or executables with build logs, diagnostics, cancellation, and a copyable report. Each compiler family remembers its settings.

Install and open

Use Python 3.11–3.13. Installation includes PySide6, NumPy, Numba, Jedi, autopep8, and their required supporting packages. Ting's local review runtime is bundled with PyCForge.

On Windows:

py -m pip install pycforge
py -m pycforge.ide

On macOS or Linux:

python -m pip install pycforge
python -m pycforge.ide

The installed pycforge-workspace command also opens the desktop app. Add --upgrade to the install command to update an existing installation. For a downloaded wheel, substitute its path for pycforge and allow pip to install dependencies; omit --no-deps.

PyCForge declares its application dependencies without version pins and does not reject installed dependency version numbers. The libraries retain their own compatibility requirements. Startup loads the application resources, offline Help, and local numerical routines before opening the workspace.

Conversion coverage

Select Transpile → Typed or Transpile → Runtime, then click Transpile or press Ctrl+Enter. The checkmark identifies the active mode, and the choice is remembered between launches. Choosing a mode does not start a conversion; changing it marks existing C output stale until you transpile again.

Text, collections, and everyday operations

Runtime conversion supports practical text-processing work: trim and normalize strings, split input into fields, join output, parse integer/float text, and build formatted reports. F-strings and str.format() support documented precision, alignment, width, and value conversions; nested containers can be printed with their supported Python representations.

Mutable lists support item and slice changes, append, extend, insert, pop, remove, sort, reverse, copy, clear, and index. Dictionaries preserve insertion order and support lookup, deletion, merging, updates, and live key/value/item views. Sets and frozen sets support membership, algebra, and subset comparisons. Passing mutable containers and instances between converted functions preserves their shared identity.

Everyday operations include sum, min, max, abs, round, any, all, stable sorted, lazy enumerate and zip, reversed, and supported iter/next use. These combine with comprehensions, classes, functions, defaults, and keyword calls to support connected processing tasks.

Functions, objects, and annotations

Typed mode accepts immutable records with int/float/bool fields and nested records as positional function parameters and return values. Constructors and record-returning calls can appear directly in arguments and returns; fields can be read from their results or through nested records. Locals support record aliases, exact initialized class annotations, chained assignment, and flat tuple/list-literal unpacking. Fixed local lists and tuples hold 1–64 records of one exact class, with literal indexing and ordered loops. Import a record class directly from its defining supplied module, with an optional alias, to use it across modules; structurally identical classes remain distinct types.

Generated C copies the complete record by value, including nested fields. Layouts are acyclic, with up to eight record levels and 256 expanded scalar fields per record; fixed record collections allow up to 4096 scalar fields in total. Record locals and parameters support same-class reassignment in branches and loops, with initialization required on every path reaching a read. Field mutation, identity and whole-record equality checks, record keyword calls, defaults, and recursive record calls remain outside the supported forms. The HTML Help includes complete factory, nested-record, local-binding, collection, and external C caller examples, with the exact supported forms and limits.

Runtime mode supports first-class functions, ordinary bound methods, nested functions, and lambdas that capture surrounding variables or default values. Closures can update enclosing bindings through nonlocal. Function and method decorators can retain state and forward *args and **kwargs.

Classes declare their fields and initialize instances through __init__. Single and multiple inheritance follow Python's C3 method resolution order, including diamond hierarchies, imported bases, overrides, and cooperative super() calls. Instances keep one shared set of fields, and isinstance and issubclass recognize every declared base. Constructors follow the calls written in the Python source.

Optional annotations include supported unions and container types. PyCForge checks annotated function, assignment, and field boundaries when generated Runtime C executes; ordinary Python does not enforce those annotations. Container annotations check their current contents at those boundaries; they do not permanently restrict later mutation through another alias.

Programs across multiple files

Open the required Python documents and choose the primary module before transpiling. Runtime imports can share functions, classes, and immutable scalar/tuple constants through aliases and re-exports. Each module has its own namespace; initialization occurs once per generated C context, preserving shared defaults and class identity.

The CLI accepts additional modules explicitly:

pycforge convert main.py --runtime-values --module helper=helper.py --output program.c

Repeat --module ID=PATH for additional files. Constants-only companion modules are supported. Imports resolve only against the supplied documents; PyCForge does not discover files or translate installed Python packages automatically.

After a successful current Typed conversion, export separate C modules from the File menu. The ZIP contains a source/header pair for each module, shared type declarations, and an ABI manifest describing the generated interfaces and ownership. Compile each generated .c file once and link the objects with your C caller. Record layouts and signatures are included. Regenerate and rebuild the complete export after source, bundle, or converter changes; a stable binary ABI is not promised. Separate module export is not available in Runtime mode.

Read, process, and write UTF-8 files

Runtime mode connects scoped open calls with string operations, collections, sorting, numeric parsing, and formatting. Read whole text or character-sized portions, iterate through lines, call processing helpers in another module, and write or append the result.

Supported file operations include read, readline, readlines, write, writelines, flush, tell, bounded seek, and early close. Unicode filenames and documented newline handling are supported. Position bookmarks belong to the same open handle; they are not arbitrary byte or character offsets. Exclusive creation and r+, w+, a+, and x+ update modes are supported. Switching between reading and writing requires a successful explicit seek; read-derived nonzero bookmarks do not permit writes. Handles close on normal scope exits, return, break, continue, and runtime errors. Returned text remains available for subsequent processing. Help includes complete file-processing examples and the positioning rules.

Python editing tools

Jedi provides offline completion, parameter hints, definition navigation, and name analysis. Autopep8 provides requested document or selection formatting. The compact Edit menu groups Selection, Lines, Find and Replace, Code, and Folding Functions; overflow submenus keep commands accessible on short displays.

• Write and navigate: completion with Ctrl+Space, parameter hints with Ctrl+Shift+Space, Go to Definition with F12, and return with Alt+Left. Automatic suggestions are optional.
• Edit several places: smart bracket/quote pairs, selection wrapping, and multiple cursors through Ctrl+D, Ctrl+Alt+L, or Alt+click; Escape returns to one cursor.
• Find and replace precisely: regular expressions, replacement within a captured selection, and reviewed replacement across open documents with Ctrl+Shift+H.
• Rename with review: F2 previews changes to statically resolved names in the current Python document before you apply them. Review dynamic references, string-based keyword names, and callers in other files separately.
• Format with undo: Alt+Shift+F formats the document; Ctrl+K, Ctrl+F formats a selection while preserving unselected lines. Formatting preserves the Python syntax tree.
• Browse and copy definitions: right-click the Python gutter to open Classes & Functions. A panel with a short progress bar covers the tree while definitions load, then disappears when the tree is ready. Double-click or press Enter to jump to a definition; the left-side title-bar Copy icon copies its complete source, including decorators and indentation, without moving either editor view.

Completion and formatting are available independently of conversion coverage. Background analysis uses cached results, cancellation, and process deadlines; edits invalidate stale results. Cross-file replacement keeps undo history for each open document. Save edited buffers explicitly. Help explains the navigator's source-size limits and the boundaries of document-local rename.

Project bundles

Use File → Project → Save Project to bundle your open Python modules, current editor text, tab order, primary module, and conversion mode in one .pcfproj file. Open Project shows a preview and loads the bundle into a new working folder. Create Checkpoint and Project History let you name, compare, and restore earlier versions, with a recovery checkpoint saved before each restore.

Project saves include unsaved editor text; Save Python and Save All Python write the separate .py files. Bundles contain Python sources and checkpoints, so keep data files and other required resources separately. The built-in Help explains saving, restoring, and returning to a project.

First conversions

Save this as input.py, select Transpile → Typed, and click Transpile:

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

The equivalent command is:

pycforge convert input.py --output generated.c

For Runtime mode, save this as greeting.py:

def greeting(name: str, *, suffix: str = "!") -> str:
    return f"Hello, {name.strip()}{suffix}"

pycforge convert greeting.py --runtime-values --output greeting.c

These examples produce callable C functions. Use a C caller or provide an eligible entry function when building an executable.

Compile C

After transpiling, choose Transpile → Compile C… (Ctrl+Shift+Enter). Select the compiler family and executable, target, object or executable output, entry function, and optimization. The dialog shows build logs, diagnostics, elapsed time, cancellation, and Copy Report. Editing the source cancels a build that would otherwise use outdated input.

Executable entries take no arguments: Typed entries return int; Runtime entries return int or None. Runtime executable wrappers release their memory context before exiting. Install the chosen compiler and its matching system headers, libraries, and linker separately. MSVC and Clang-cl need a configured Visual Studio developer environment; PCFC11 0.1.1+ needs its adjacent include directory and a GCC-compatible assembler/linker, using MinGW-w64 UCRT64 on Windows.

For app.py containing def start() -> int: return 0:

python -m pycforge.build app.py --entry main.start --compiler-family gcc --compiler /path/to/gcc --output program

Add --runtime-values for Runtime conversion. The compiler-family choices are pcfc11, gcc, clang, msvc, and clang-cl; Help explains their target and optimization options. Conversion and C builds do not execute your Python or generated program. Use Tools → Run Python to run a saved Python module explicitly in a separate terminal. The generated Runtime C includes its value routines and does not require Python, PySide6, NumPy, Numba, or Ting when executed on a compatible host.

Ting agent feedback

Six local Ting agents review syntax, semantics, ownership, C lowering, evidence, and resources. Open Ting in the status bar to inspect findings, and use the Flow Map to follow the conversion evidence behind each review.

Ting runs offline. Its feedback is advisory and leaves your source and conversion result unchanged. Each review identifies the checks available for that conversion; it does not replace compilation or comparison with your program's intended behavior.

Command line and Python API

Use pycforge --help for commands and options, or pycforge --format json convert input.py for structured output. Convert source text from Python with:

from pycforge import ConversionRequest, PythonToCConverter

source = "def add(left: int, right: int) -> int:\n    return left + right\n"
result = PythonToCConverter().convert(ConversionRequest.from_source(source))

if result.generated_c is not None:
    print(result.generated_c)
for diagnostic in result.diagnostics:
    print(diagnostic.code, diagnostic.message)

The Python API supports integration into other applications through structured requests and results, diagnostics, progress callbacks, and cooperative cancellation. Its in-app guide documents these contracts, threading responsibilities, Runtime requests, source bundles, and generated C interfaces.

Help and supported boundaries

Press F1 or choose Help → PyCForge Help… for 30 searchable offline pages covering the editor, conversion tables, examples, diagnostics, Ting, shortcuts, and C integration. Separate references describe Typed and Runtime behavior, including a multi-file read/process/write example. Selected PyCForge caveats boxes explain practical conversion details beside relevant examples.

PyCForge converts the documented Python forms. Integers use signed 64-bit values; generated Runtime values belong to a memory context. Destroying the context releases them, or C callers can explicitly collect unreachable values at documented idle boundaries while retaining live roots. Collection is not automatic inside Python loops and does not reset resource budgets. Exact ForgeLens mappings and generated-C structural checks cover Typed and Runtime conversion; they do not replace compilation and behavior testing.

Runtime exception recovery supports a documented set of built-in errors; exception objects, except … as … bindings, custom exception classes, bare re-raise, and chaining remain unsupported. Resource exhaustion is terminal and skips Python handlers and finally bodies; automatic file cleanup still runs. General third-party library translation, asynchronous code, generators, general reflection, dynamic bases, properties, static/class methods, writable module globals, and cyclic/relative/star imports are outside the supported forms. Consult Help for numeric rules, resource limits, and C caller requirements.

License

PyCForge is free software under the GNU General Public License v3.0 only. The distribution includes LICENSE and third-party notices.

Conversion bug tracker

Confirmed conversion issues and the release containing each fix. Regression tests cover the reported cases and related edge cases; this record is not a guarantee that every Python program converts without defects.

Crucible powers PyCForge's Typed and Runtime conversion. Its conversion pipeline combines deterministic C generation, source-mapped diagnostics, and explicit checks on supported Python forms. Regression coverage includes Python-versus-C execution, multi-module programs, and separately compiled C interfaces. The practical HTML Help documents how to use that scope and where its boundaries lie.

Contact Robert Cecil rcttcr5@icloud.com for request or security assistance