USING PYCFORGE

Command line and Python API

Convert files from a terminal or submit source text through the Python API. Select the same conversion mode used by your source examples.

Command-line conversion

# Typed conversion
pycforge convert input.py --output generated.c

# Runtime value conversion
pycforge convert input.py --runtime-values --output generated.c

# Check source without saving C
pycforge validate --source input.py
pycforge validate --source input.py --runtime-values

# Return a structured result
pycforge --format json convert input.py --runtime-values

# View command options
pycforge convert --help

If conversion fails, an existing output file is left untouched. Check the command result and diagnostics before treating a destination file as current.

The CLI accepts a primary source path and repeated --module ID=PATH companions. Both conversion modes also accept the workspace bundle or SourceBundle API below. --format json is a global option and precedes the subcommand. With --output, a successful conversion writes C without printing the full result; run validate or convert without --output to inspect all diagnostics.

For automation, exit status 0 means conversion succeeded (possibly with warnings), 2 means rejected source, 3 means cancelled, 4 means internal failure, and 74 means a file read/write error. Command-line syntax errors are reported separately by the argument parser; read the message as well as the exit status. A successful validate parses and converts source but does not build or execute the generated C.

Typed source requests

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 default request selects typed conversion. Source text is parsed as data and is not executed.

Runtime value requests

from pycforge import ConversionRequest, PythonToCConverter
from pycforge.converter.runtime_values.service import request_options

source = "def greeting(name: str) -> str:\n    return 'Hello, ' + name\n"
request = ConversionRequest.from_source(source, **request_options())
result = PythonToCConverter().convert(request)

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

Use all options returned by request_options() together. Runtime conversion accepts explicit source bundles and can return C with warnings. Review every diagnostic, including the conversion-contract information, before using the result.

Typed requests with multiple files

from pycforge import (
    ConversionRequest, PythonToCConverter,
    SourceBundle, SourceDocumentInput,
)

main_text = """from math_tools import double

def run(value: int) -> int:
    return double(value)
"""
tools_text = """def double(value: int) -> int:
    return value * 2
"""

bundle = SourceBundle(
    primary=SourceDocumentInput("main.py", main_text, "main"),
    companions=(SourceDocumentInput(
        "math_tools.py", tools_text, "math_tools"
    ),),
)
result = PythonToCConverter().convert(
    ConversionRequest(source_bundle=bundle)
)

The bundle example converts run(4) to a function that returns 8. Read its actual generated declaration: combined modules can have qualified C names.

Supply every imported file explicitly and match its module name to the import. The converter does not discover modules on disk. See Importing functions.

Runtime modules through the API

Supply every document with an exact module ID. The first is primary. This example converts a constant imported from a companion:

from pycforge import ConversionRequest, PythonToCConverter
from pycforge.converter.core.request import SourceBundle, SourceDocumentInput
from pycforge.converter.runtime_values.service import request_options

bundle = SourceBundle(
    SourceDocumentInput("main.py", "from config import VALUE\ndef main():\n    return VALUE\n", "main"),
    (SourceDocumentInput("config.py", "VALUE = 0\n", "config"),),
)
result = PythonToCConverter().convert(
    ConversionRequest(bundle, **request_options())
)
assert result.generated_c is not None

From the terminal use pycforge convert main.py --runtime-values --module config=config.py --output result.c. Repeat --module ID=PATH for each companion and use --module-id ID to change the primary ID. The same options work with validate --source. Neither conversion nor validation executes the program.

File-workflow limits through the API

Choose bounds for the workload before conversion. This example allows up to 4 MiB of input per open handle, 8 MiB of retained read buffers, four open handles, and 512 file operations per C context. The source path is used only when the compiled program calls load; conversion does not read the data file.

from pycforge import ConversionRequest, PythonToCConverter
from pycforge.converter.core.resource_policy import ResourcePolicy
from pycforge.converter.runtime_values.service import request_options

source = """def load(path):
    with open(path, encoding="utf-8") as handle:
        return handle.read()
"""
policy = ResourcePolicy(
    max_file_read_bytes=4 * 1024 * 1024,
    max_live_owned_bytes=8 * 1024 * 1024,
    max_open_files=4,
    max_file_operations=512,
)
request = ConversionRequest.from_source(
    source, resource_policy=policy, **request_options()
)
result = PythonToCConverter().convert(request)
print(result.status.value)

The read ceiling is 16 MiB; the retained-read ceiling is 16 MiB plus one byte. Retained capacity must cover at least one maximum read and its terminator. Open-handle and operation ceilings are eight and 1,024. Read buffers and other values also consume the general runtime arena. See how file operations are counted.

Optional native compilation

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

Add --runtime-values for Runtime conversion, --companion helpers=helpers.py for each supplied module, --kind object for object output or --optimize 1 for O1. Select pcfc11, gcc, clang, msvc or clang-cl with --compiler-family; PCFC11 is the default. O2 and O3 depend on the selected family. Executable entries take no parameters; Typed returns int, Runtime returns int or None. The command compiles but never runs the program. The desktop uses the same build service; see Compile C.

Use the result

Inspect result.status, result.diagnostics, and result.generated_c. Successful output may carry warnings; rejected, cancelled, and internally failed conversions do not supply new usable C. Preserve the source and selected settings, then compile and test generated code with your own C11 toolchain.