USING PYCFORGE

Conversion import documentation

A conversion import supplies an explicitly declared set of functions and constants. Its offline reference describes the exact registered package version.

Read the selected import's Help

1. Open Tools → Register Conversion Imports, or its direct toolbar button.
2. Select the package and read its status, author, date and version.
3. Choose Import Help… to open its searchable offline manual.

The manual includes the author overview, usage, limitations and release notes, followed by a generated function reference, parameter explanations, results, constants and fixture examples. Example sources and expected output are displayed only; opening Help never runs them. A disabled package can still be inspected. Its icon is gray, and the import manual uses a double-width vertical scrollbar.

Bundled math, NumPy and JSON include this documentation. All appear in the register automatically and can be disabled independently. The small standard set covers scalar, array and structured-value contracts without limiting the SDK to these libraries. Custom package authors provide their explanations through the separate SDK. The SDK generates the structure and the engine generates reference facts from the accepted conversion contract.

Understand registration status

The import dialog appears with a small copper loading panel while it checks the list. Close cancels the pending check; Refresh retries it. Import controls and their manuals use the original code-bracket PyCForge icon.

Startup checks enabled conversion imports through the existing single progress bar. Unavailable imports are reported after the workspace opens. A package that times out or loses its checking process remains unavailable for the session until an explicit Refresh succeeds. Conversion and autocomplete use the same session exclusions; unavailable namespaces never fall back to an installed Python library.

Registration keeps a separate copy of each package. Editing the author's original file does not change that copy. Changes to a registered copy are checked again when conversion or autocomplete obtains its package snapshot. Refresh updates the list and retires outdated conversion results and suggestions.

The host allows five seconds to start a checking process, two seconds per package after startup, and a fifteen-second checking budget, followed by bounded process cleanup. Files must be regular files. The existing limits of 64 custom registrations and 2 MiB per package remain. Opening Help and changing registrations also run under time limits. A folder registration accepts at most 64 package files among at most 4096 directory entries.

A damaged registration index is left untouched; the dialog explains the problem and remains read-only until the index is repaired and Refresh succeeds. Package errors belong in the SDK; an unreadable index is a local registration problem. Safe start does not read or change custom registrations. If an explicit registration operation is interrupted, Refresh shows the actual saved selection; completed entries may already have been registered. The author's original files are preserved.

Documented scalar package format 0.2, array package format 0.1 and value package format 0.1 require complete structured Help, exact export coverage, matching conversion facts, linked example snapshots and integrity binding. Registration checks those facts and compatibility; it does not run the SDK's native tests or certify all possible inputs.

Legacy format 0.1 packages remain usable. Their Help is clearly labeled generated contract reference only; it contains no packaged author manual or verified example snapshots. Rebuild in SDK 0.3 or later with a compatible engine to add that documentation. An older engine refuses the new package format explicitly.

Correct a call without disabling its library

An invalid source call does not invalidate an otherwise valid package. After a rejected conversion, the Diagnostics panel and the quick-diagnostics toolbar button show the same source diagnostic.

Wrong dynamic value types can instead raise TypeError when the generated program runs. Those are runtime exceptions, not failed-transpilation diagnostics, and may be handled with supported exception handling. The quick-diagnostics button is for current rejected or failed conversions.

Signatures use / for positional-only arguments and * for keyword-only arguments. Defaults are shown in call hints and the selected package Help. Completion suggests only names accepted by that package, excluding already supplied slots. These contracts require scalar profile 0.3; old packages retain their original fixed positional calls.

Bundled NumPy arrays

Select the included NumPy 0.3.0 entry, confirm Ready, and select Runtime. A separate registration is unnecessary on a new installation. Existing custom NumPy registrations and disabled selections are preserved during upgrade. This package supports one-dimensional contiguous finite float64 arrays. The generated executable does not load NumPy or Python.

*import numpy as np

def main():
    values = np.array([1, 2, 3], dtype="float64")
    shared = values
    copied = np.copy(values)
    shared[0] = 9
    print(values.tolist(), copied.tolist())
    print(np.add(values, 2).tolist())
    return 0

The example prints [9.0, 2.0, 3.0] and [1.0, 2.0, 3.0], then [11.0, 4.0, 5.0]. Assignment shares identity; array construction, copy and arithmetic return independent storage.

Finite values only. Nonfinite inputs and arithmetic overflow are explicitly refused; NumPy warning/seterr policies are not implemented. Other reductions, dtype objects, array comparisons and array formatting are unsupported. Use tolist() for display. An empty or multi-element array cannot be used as a Boolean condition.

Reduction calls accept named a and axis arguments. Empty reductions raise ValueError. No automatic sequence conversion, axis tuples, out, keepdims, where, initial or array reduction methods are supported. If a selected minimum/maximum is zero and both positive and negative zero occur, the value reduction raises ValueError because NumPy's zero sign can depend on reduction order. Single-sign zero extrema retain their sign; argmin and argmax accept mixed signs and return the first tied index.

*import numpy as np

def main():
    values = np.array([4, -3, 8, -3, 8], dtype="float64")
    print(np.min(values), np.max(values, axis=-1))
    print(np.argmin(a=values), np.argmax(values, axis=0))
    return 0

This prints -3.0 8.0, then 1 2. Equal extrema keep the first index. The returned scalars remain unchanged if you later modify the array.

Arrays live in the existing Runtime memory context. Function returns preserve them; C callers must keep the context alive and retain roots during explicit boundary collection. The context byte and work budgets apply. Ordinary type/shape/bounds errors are catchable. Resource exhaustion remains fatal; the executable wrapper releases the context on exit.

Bundled JSON values

Select Runtime and declare *import json. JSON 0.1.0 supplies loads(s) and dumps(obj, *, ensure_ascii=True, separators=None). These are generated C operations; the executable does not need Python or a JSON library.

*import json

def main():
    record = json.loads('{"name":"PCF","values":[1,2,3]}')
    record["values"].append(4)
    print(json.dumps(record, separators=(",", ":")))
    return 0

This prints {"name":"PCF","values":[1,2,3,4]}. Strings, None, bool, signed int64, finite float64, lists, tuples and dictionaries with string keys are supported. JSON arrays become lists; tuples serialize as arrays. Dictionary order is preserved. Duplicate JSON object names keep the last value and the first position.

Unicode scalar characters, escapes, surrogate pairs and embedded NUL are supported. ensure_ascii=False emits Unicode directly. Lone surrogates, nonfinite numbers, arbitrary-precision integers, bytes, custom encoders, hooks, streams, indentation and key sorting are outside this profile. Use normal file.read()/file.write() with loads/dumps when processing supported text files.

The profile allows at most 64 nested containers, 1 MiB of UTF-8 input/output and 1024 bytes per numeric token, plus the shared Runtime byte/work budgets. Cycles, malformed text and unsupported types raise catchable errors; syntax errors use ValueError without JSONDecodeError attributes. Resource exhaustion is fatal. Numeric parsing requires a C-compatible numeric locale and nearest rounding. Inputs are unchanged, failed codec calls release partial allocations, and returned nested values participate in the existing GC root and context lifetime rules.

SDK author workflow

Use templates to choose a starter. Array and structured-value authors choose an operation, export name, stable identity and summary; memory and parameter rules are supplied by the engine. Edit the project, run scan, complete each indicated field, then run verify and build. The document command adds missing author fields without replacing existing explanations. Generated blanks remain incomplete. Each function's Help example must name a passing native fixture containing that operation.

Verification binds the saved project, documentation, fixtures, engine, SDK and compiler. Changed inputs require verification again. Build produces a deterministic package from matching evidence and does not register it automatically. The SDK supplies Python, console and optional PySide6 interfaces. Its desktop Scanner uses the readiness service to check packaging eligibility; console scan retains the authoring-only check. Only explicit Verify fixtures compiles and runs examples.