Metadata-Version: 2.4
Name: pycforge
Version: 1.0.2
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 focused Python-to-C source transpiler with a complete desktop
workspace, command-line tools, and a Python API. It converts its documented,
typed Python subset into readable C11 source. Unsupported input is rejected
with clear diagnostics instead of being guessed or silently changed.

![PyCForge 1.0.2 workspace](https://i.ibb.co/wr4g4FgT/pcf-main.png)

## Install, upgrade, and open

PyCForge requires Python 3.11 or newer. PySide6 and the complete desktop
application are installed automatically.

On Windows, install PyCForge and open the workspace with:

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

To upgrade an existing Windows installation and open it immediately:

```powershell
py -m pip install --upgrade pycforge
py -m pycforge.ide
```

On macOS or Linux:

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

To upgrade on macOS or Linux:

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

`py -m pycforge.ide` is the easiest Windows launch command because it works
immediately after either installation or upgrade. The installed
`pycforge-workspace` command opens the same application.

## What PyCForge provides

- A professional dark desktop workspace for opening, editing, organizing, and
  transpiling Python source bundles of up to 64 files.
- Side-by-side Python and generated C, with exact ForgeLens navigation between
  corresponding source locations.
- Tabs, split source view, function folding, outline, search and replace,
  command palette, conversion history, and remembered workspace sessions.
- Read-only generated C with diagnostics, mappings, conversion summaries,
  decision traces, and optional telemetry views.
- Cancellable background transpilation that keeps the interface responsive.
- Deterministic output for the same source bundle and settings.
- Clear rejection of Python outside the supported conversion boundary.
- A headless command-line interface and a structured Python API for automation.
- Independent Python and generated-C text sizing, accessible controls, and
  display-aware window sizing.
- Searchable documentation built directly into the application.

PyCForge currently supports selected typed functions, scalar expressions,
conditionals, bounded loops, direct calls, fixed containers and records,
fixed-set membership, explicit module bundles, and a bounded UTF-8 file I/O
profile. The in-app documentation gives the exact accepted and rejected forms.

## Ting agent integration

PyCForge includes six deterministic Ting agents that examine each completed or
rejected conversion from different engineering perspectives:

- syntax admission;
- semantic preservation;
- ownership and lifetime;
- C lowering readiness;
- release verification; and
- capability and resource limits.

The Ting agents use authenticated local rulepacks and bounded work limits. They
receive structural evidence rather than source text, run without a network
connection, and report their evidence and gaps in a dedicated read-only
feedback window.

Ting currently operates in **shadow evaluation** mode. Its feedback can help
review a conversion, but it never changes, approves, blocks, or publishes the
generated C.

![PyCForge Ting agent feedback](https://i.ibb.co/TqN9zv64/pcf-ting-agents.png)

## Built-in help and documentation

Press **F1** or choose **Help → PyCForge Help…** to open 14 searchable offline
help pages. They cover the workspace, supported Python, generated C, Ting
feedback, diagnostics, safety limits, shortcuts, the CLI, and the Python API.
No browser or network connection is required. The source distribution also
includes `PyCForge_v0_16_0_Programmers_Conversion_Guide.pdf`.

## Command line

Convert a Python file to C:

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

Return the structured conversion result as JSON:

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

See every command and option:

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

## Safety boundary

PyCForge reads supplied Python as source data. It does not import or execute
that Python, and it does not compile, link, load, or run the generated C. Review
the built-in **Safety and limits** page before using generated code in another
build system.

## PyCForge 1.0.2

Version 1.0.2 presents a shorter feature-focused README with current workspace
and Ting feedback images. It also makes the close control in the top
notification banner follow the notification's information, success, warning,
or error color while leaving the rest of the reviewed interface unchanged.

## License

PyCForge is free software released under the GNU General Public License v3.0
only. The complete license text is included in `LICENSE`.
