Metadata-Version: 2.4
Name: pycforge
Version: 1.1.3
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.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: licenses/Python.txt
License-File: licenses/Ryu-Boost-1.0.txt
License-File: licenses/TING_REASONER.txt
License-File: licenses/Unicode.txt
Requires-Dist: PySide6<7,>=6.8
Requires-Dist: numpy<2.4,>=2.3.5
Requires-Dist: numba<0.64,>=0.63.1
Dynamic: license-file

# PyCForge

PyCForge is a Python-to-C source transpiler and PySide6 desktop IDE. It converts
supported Python into readable C11 and brings editing, diagnostics, and
generated-code inspection into one workspace, with a command-line interface
and Python API for automated workflows.

![PyCForge workspace](https://res.cloudinary.com/vppzdwxg/image/upload/v1789348864/pcf_main.png)

## Install, upgrade, and open

PyCForge supports Python 3.11–3.13. PySide6, NumPy, Numba, and the desktop
application are installed automatically.

On Windows:

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

On macOS or Linux:

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

To upgrade an existing installation, use `py -m pip install --upgrade pycforge`
on Windows or `python -m pip install --upgrade pycforge` on macOS or Linux.
The installed `pycforge-workspace` command also opens the application.
The splash window prepares application resources, offline help, and Ting's
NumPy/Numba numerical routines before the workspace opens.

## What PyCForge provides

- Python editing with tabs, split view, function folding, outline, search and
  replace, and a command palette.
- Side-by-side Python and read-only generated C, with diagnostics, conversion
  details, and history.
- Source bundles of up to 64 files for typed conversion, with ForgeLens
  navigation between mapped Python and C locations.
- Cancellable background conversion and clear identification of output that
  needs to be regenerated after an edit.
- Saved workspace layouts, independent Python and C text sizes, and searchable
  offline documentation.

## Python-to-C conversion

Choose the conversion mode that matches the source and the C interface you need.

| Mode | Supported uses | Select with |
| --- | --- | --- |
| Typed conversion | Annotated functions, scalar variables, module constants, string inspection, fixed containers, immutable records, imports between supplied source files, and bounded UTF-8 file operations. | **Transpile Source Bundle** or the default `convert` command. |
| Runtime value conversion | Constructed Unicode strings, shared mutable lists and class instances, mixed lists and tuples, union and container annotations, list comprehensions, lambdas with captured variables, defaults and keyword arguments, numeric text conversion, and practical string methods. | **Transpile Runtime Values** in the Transpile menu, or `convert --runtime-values`. |

Runtime value conversion accepts one source document. Its generated C includes
the value and memory routines needed for strings, containers, objects, and
closures. Lists and instances retain their identity when passed to functions;
strings remain immutable. Annotations check values at function and assignment
boundaries. Container annotations check their contents at those boundaries
without permanently constraining writes through other aliases.

Runtime conversion includes these additional everyday Python forms:

- Default arguments, keyword calls, positional-only and keyword-only parameters,
  including constructors, bound methods, and lambdas such as `lambda i=i: i`.
- Unicode `lower()` and `upper()`, `strip()` / `lstrip()` / `rstrip()`, and
  `split()` with whitespace handling, separators, and `maxsplit`.
- `int()` and `float()` from numeric strings, optional integer bases,
  float-to-string output, simple f-string fields, and `print(sep=..., end=...)`.
- Empty `list()`, `tuple()`, `str()`, `int()`, `float()`, and `bool()` calls.

Defaults retain Python's definition-time evaluation and shared mutable values.
Simple f-strings support ordinary fields and `!s`; format specifications and
`!r` / `!a` are outside this conversion set. Unsupported methods or argument
forms receive source diagnostics when the receiver type is known.

Both modes use signed 64-bit integers and documented Python forms. The bundled
help provides separate operation tables, examples, C caller requirements, and
limits for each mode.

## First conversion

Save the following as `input.py`:

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

Open it in the workspace and choose **Transpile Source Bundle**, or run:

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

For runtime string construction, save this as `greeting.py`:

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

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

## Ting agent integration

Six local Ting agents review syntax, semantics, ownership, C lowering,
verification evidence, and resource requirements. Open the **Ting** control
in the status bar to inspect their findings. The **Flow Map** displays the
relationship between the conversion evidence and each review.

Ting feedback is advisory. It uses structural evidence, runs offline, and
leaves source code and conversion results unchanged. A review describes the
checks available for the selected conversion; external compilation and
execution comparisons require your own toolchain and test inputs.

![PyCForge Ting agent feedback](https://res.cloudinary.com/vppzdwxg/image/upload/v1789349066/pcf_ting_agents.png)

## Built-in help and documentation

Press **F1** or choose **Help → PyCForge Help…** to open the searchable offline
guide. Its 20 pages cover installation, the workspace, both conversion modes,
strings, containers, classes, defaults and keyword calls, function annotations, lambdas, comprehensions,
file operations, diagnostics, Ting feedback, shortcuts, and C integration.
Use the supported-conversions table to select a mode before converting a
larger source file.

## Command line and Python API

Use `pycforge --help` to view commands and options. For a structured result:

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

Convert source text from Python:

```python
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 in-app API guide includes runtime value requests and multiple-file bundles.

## Using generated C

PyCForge reads Python as source data and produces C source. It does not execute
the supplied Python or compile, link, or run generated C. Review diagnostics,
save a successful current result, and build it with your C11 toolchain.
Follow the help's memory, input, and error-handling requirements for the selected
mode, then compare C results with Python for representative inputs.

## License

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