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.

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 one document 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)
)

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

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.