Metadata-Version: 2.4
Name: pycforge
Version: 1.0.1
Summary: Deterministic bounded Python-to-C source transpiler
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://pypi.org/project/pycforge/
Project-URL: Download, https://pypi.org/project/pycforge/#files
Keywords: python,c,transpiler,pyside6,qt6,desktop
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: licenses/TING_REASONER.txt
Requires-Dist: PySide6<7,>=6.8
Dynamic: license-file

# PyCForge

[![PyPI](https://img.shields.io/pypi/v/pycforge.svg)](https://pypi.org/project/pycforge/)
[![Python](https://img.shields.io/pypi/pyversions/pycforge.svg)](https://pypi.org/project/pycforge/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://pypi.org/project/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.

![PyCForge 1.0.1 workspace](docs/images/pycforge-workspace-0.16.3.png)

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](docs/PyCForge_v0_16_0_Programmers_Conversion_Guide.pdf)
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:

```bash
python -m pip install pycforge
```

On Windows, use the Python Launcher:

```powershell
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:

```powershell
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:

```powershell
.\.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:

```bash
python -m pip install --upgrade pycforge
```

```powershell
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:

```bash
pycforge-workspace
```

The equivalent module command is:

```bash
python -m pycforge.ide
```

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

```powershell
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`:

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

Convert it:

```bash
pycforge convert example.py --output example.c
```

PyCForge produces:

```c
#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:

```bash
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:

```bash
pycforge convert input.py --output generated.c
```

Emit the structured result as JSON:

```bash
pycforge --format json convert input.py
```

See all commands and options:

```bash
pycforge --help
```

## Python API

```python
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](docs/images/pycforge-help-0.16.3.png)
- [Archived 0.16.0 Programmer's Conversion Guide](docs/PyCForge_v0_16_0_Programmers_Conversion_Guide.pdf)
- `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:

```bash
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`.
