GETTING STARTED
Select a mode by the Python features and C interface your program needs. Each column describes that mode's supported forms.
| Feature | Typed conversion | Runtime value conversion |
|---|---|---|
| Selection | Transpile → Typed, then Transpile; default CLI/API request. | Transpile → Runtime, then Transpile; CLI --runtime-values; API request_options(). |
| Source files | 1–64 supplied modules; direct function and immutable-record imports, aliases, and record-only companions. | 1–64 supplied modules; function/class/constant imports, aliases, re-exports, and immutable module constants. |
| Function values and types | Annotated parameters and results; consistent scalar locals; direct calls and required keyword arguments. | Optional parameter/result annotations, unions, container types, first-class functions, nested closures with nonlocal bindings, function/method decorators, bound methods, and lambdas; defaults, positional-only/keyword-only and variadic parameters, and expanded calls. |
| Strings | Runtime length, comparison, search, membership, prefix/suffix checks; additional constant-text operations. | Runtime construction, repetition, Unicode indexing/slicing, strip/lstrip/rstrip, lower/upper, split with maxsplit, join, replace, inspection, f-string precision/alignment, repr/ascii, format and str.format. |
| Lists and tuples | Fixed local homogeneous values; literal indexing and iteration. | Mixed and nested values, dynamic indices, slices, function arguments/results, and shared lists with item/slice assignment and deletion, append/extend, insert/pop/remove, sort/reverse, copy/clear, index, and starred packing/unpacking. |
| Dictionaries | Fixed local dictionaries. | Ordered mutable dictionaries, scalar/tuple/frozen-set keys, nested values, key lookup and deletion, merging/unpacking, fromkeys, update, live views, and forward/reverse iteration. |
| Numeric operators | Documented scalar arithmetic; no power or bitwise operators. | Checked int64 arithmetic, finite floating floor division/remainder, powers and modular powers, bitwise operators, and shifts. |
| Everyday builtins | Restricted documented scalar forms. | sum, min/max, abs, round, enumerate, zip, any/all, sorted, iter/next, reversed, pow, divmod, and builtin function values. |
| Sets | Numeric/Boolean set membership. | Mutable sets, frozen sets, hashable elements, algebra, subset comparisons, methods, and comprehensions. |
| Classes | Immutable scalar and nested records; fresh local aliases and initialized class annotations, constructor/factory field reads, fixed local record lists/tuples, and typed positional parameters/returns across supplied modules. Exact declaring class identity and bounded inline layouts. | Annotated mutable fields, single and multiple inheritance with C3 lookup, method overrides, super calls, and shared instances. |
| Control flow | Branches, integer ranges with a literal nonzero step, fixed-container loops, break/continue, loop else. | Branches, sequence/range/dictionary/view and lazy iterator loops, conditional expressions, short-circuit values, break/continue, loop else. |
| List, dictionary, and set comprehensions | Not supported. | Multiple generators, filters, dependent iterables, and fixed or starred unpacking. |
| Exceptions | Existing status-return interfaces. | Selected try/except/else/finally and literal raises, with terminal resource limits. See Exceptions and cleanup. |
| Files | Bounded UTF-8 read/write entry points for C callers. | UTF-8 read/process/write workflows across functions/modules; line iteration, sized reads, append, exclusive creation, text bookmarks, seek-separated update modes, and automatic handle cleanup. See File-processing workflows. |
| C interface | Scalar functions and struct values passed/returned by value, single-file or separate module exports, and documented file status/ownership rules. | Tagged values and a caller-owned memory context. |
| Code inspection | Typed conversion validation and exact ForgeLens mappings. | Source diagnostics, generated-function names, checked runtime operations, and validated ForgeLens emission ranges. Independent output/provenance checks; no Typed C-IR semantic proof. |
For typed conversion, start with Variables, types, and strings, then Branches and loops, Containers and records, and Functions and module variables.
For runtime value conversion, start with Runtime conversion and C use, then follow the string, container, class, function, and comprehension pages in order.
Integers use signed 64-bit values. General Python libraries, exception objects, asynchronous code, generators, general reflection, dynamic base classes, and writable module globals are outside these documented forms. Source conversion does not execute Python or build the C result.
Conversion success establishes that the source can be emitted for the selected mode. It does not exercise every runtime input. Check the mode's type, memory, and arithmetic requirements when calling generated functions.
Retain the Python source, selected mode, settings, and installed version alongside generated C. Check the version through Help → About or:
python -c "import pycforge; print(pycforge.__version__)"