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, JSON, itertools and CSV include this documentation. All appear in the register automatically and can be disabled independently. The small standard set covers scalar, array, structured-value, lazy iterator and delimited-record 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.

Build an independent conversion import

The separate SDK reads the selected engine's public authoring choices. Scalar, owned array, JSON, Unicode text and lazy iterator families are available. The text-starter demonstrates trimming, splitting and joining through an independently named namespace. The text-replacement-starter adds literal Unicode replacement through function(text, old, new, count=-1), including named arguments and insertion at scalar boundaries for an empty old string. The text-predicate-starter exposes text-startswith and text-endswith through function(text, prefix_or_suffix, start=0, end=None), with Unicode-scalar bounds, named arguments and allocation-free Boolean results. These predicates select text profile 0.3; earlier declarations retain their existing profiles. The text-search-starter adds text-find, text-rfind and text-count through (text, sub, start=0, end=None), with independent int64 results and text profile 0.4. These starters supply complete Help, successful fixtures and deliberate rejection cases. Refresh the SDK after changing the engine, and read its guide for exact coverage and a human/AI author workflow.

Authors choose operation identities, export names and explanations; Crucible supplies each reviewed operation's signature, ownership and conversion rules. Unsupported Runtime methods cannot become import operations simply by adding their names. Scan, conversion verification, readiness and packaging are separate checks. Registration validates the package but does not rerun its fixtures.

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.

StatusMeaning
ReadyThe package is admitted and enabled for its declared Runtime operations.
DisabledThe package is admitted but not selected for conversion.
Cannot useRead the specific reason, then correct and rebuild the package in the SDK. A failed replacement preserves the previously usable registration.

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 execute examples 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 authored 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.

CodeCorrection
PYC4702Check that the namespace has a Ready registration.
PYC4703Select Runtime; these import routes does not support Typed conversion.
PYC4704Use a function or constant listed in the selected package's Help.
PYC4710Use dtype="float64" for the bounded array profile; other dtype literals are unsupported.
PYC4711Array reductions and concatenate accept axis=None, 0 or -1. Other literal axes are outside the supported profile.
PYC4706Use the declared names, positions and defaults. The message identifies missing values, unknown names, duplicate values or a positional-only/keyword-only misuse. Argument expansion remains unsupported.

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.12.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 owned contiguous finite float64 arrays of rank one or two. 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.

SupportedLimits
array, zeros, ones, full, copyarray and full require dtype="float64". zeros and ones default to it. Flat numeric sequences or rectangular nested rows; shape is an integer or a one-/two-item tuple/list.
add(a,b), subtract(a,b)Two matrices with exactly matching rows and columns, including empty shapes; or the existing equal-length vector/vector-scalar operands. Results own independent storage. Positional arguments only; no matrix broadcasting, out, where or dtype overrides.
multiply and +, -, *, +=, -=, *=Vectors only: equal lengths or one vector with a numeric scalar. In-place vector forms retain identity. Matrix operator forms are unsupported; use add/subtract calls for matching matrices.
divide, true_divide, / and /=Equal-length arrays or one array and a finite numeric scalar. Calls and / return independent storage; /= preserves array identity and all aliases, and leaves every element unchanged on failure. Zero divisors raise ValueError; nonfinite results raise OverflowError. Empty division performs no element operations, so an empty array divided by zero remains empty. Finite underflow, including signed zero, is permitted. No out, where, floor division or remainder.
negative, absolute, sqrtUnary calls require supported arrays and return independent storage. Negative square roots are refused. No out or where options.
concatenateA nonempty list/tuple of supported arrays; empty constituent arrays are valid. axis defaults to 0 and accepts None, 0 or -1. No dtype, out or casting options. The result copies all elements.
min, max, argmin, argmaxNonempty supported arrays; axis defaults to None and accepts integer 0 or -1. Values are independent float64 scalars; indices are int64 and choose the first tie. No output array allocation or input mutation.
matvec(x1, x2, /)
vecmat(x1, x2, /)
Matrix (m,k) times vector (k) gives an independent vector (m); vector (k) times matrix (k,n) gives an independent vector (n). Inner dimensions must match. Fixed separately rounded products and pairwise accumulation, nearest rounding, finite intermediate results and complete failure rollback. No stacks, broadcasting, sequence coercion, out or ufunc options.
matmul(x1, x2, /)Two owned matrices with shapes (m,k) and (k,n), returning independent storage of shape (m,n). Separate binary64 products and balanced pairwise accumulation; nearest ties-to-even rounding and gradual underflow. Empty inner products and zero totals are +0.0. Intermediate overflow raises OverflowError; failure preserves inputs and releases partial output. No vectors, stacks, broadcasting, @, out or dtype options.
dot(a, b)Equal-length supported arrays, positional or named arguments. Separately rounded products followed by a fixed balanced sum; no fused multiply-add or intermediate array allocation. Empty inputs and zero totals return +0.0. Product or sum overflow raises OverflowError. No scalar coercion, out, matrices or @. Inputs remain unchanged; the scalar result is independent.
sum(a, axis=None), mean(a, axis=None)Owned vectors or matrices. The default reduces all elements to an independent scalar. Matrix axes return independent vectors: 0/-2 for columns, 1/-1 for rows. Vector axes remain None/0/-1. Every slice uses fixed balanced pairwise float64 summation; mean divides by its length. Empty sums are +0.0. A required empty mean raises ValueError; an axis with no output elements returns an empty vector. Any intermediate overflow raises OverflowError. Inputs and aliases remain unchanged.
Indexing, item assignment, len, iteration, shape, size, ndim, copy(), tolist()Vectors accept integer indices and iteration. Matrices accept a[row,col], including negative indices, and len returns the row count. No Boolean indices, slicing, row views or direct matrix iteration. Both ranks support copy()/tolist(), shape, size and ndim.

The explicit matvec/vecmat, matmul, add/subtract and sum/mean calls in this table accept matrices. Other arithmetic, transforms, concatenation, dot and extrema reductions accept vectors only. Matrix add/subtract require nearest ties-to-even rounding, preserve signed zero and finite subnormals, and reject nonfinite results. Inputs remain unchanged on success or failure. Matrix construction/copy preserves shape, uses contiguous row-major storage and makes an independent writable result. Ragged rows are refused; zero dimensions are preserved. Matrix tolist() makes independent nested rows.

*import numpy as np
def main():
    grid = np.array([[1, 2], [3, 4]], dtype="float64")
    result = np.add(grid, grid)
    print(result.tolist())
    return 0

This prints [[2.0, 4.0], [6.0, 8.0]]. Use np.subtract(grid, grid) for a matching zero matrix. The owned-matrix-starter exposes the same operations as grids.combine and grids.difference under an independent namespace.

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.

Reshape into independent storage

Use np.reshape(a, shape, copy=True) to turn an existing vector or matrix into a new vector or matrix. Shape is the desired length or a tuple/list of one or two dimensions. The number of elements must stay the same. One dimension may be -1 to infer it from the others. Values stay in row-major (C) order.

*import numpy as np

def main():
    a = np.array([[1, 2, 3], [4, 5, 6]], dtype="float64")
    b = np.reshape(a, (3, 2), copy=True)
    flat = np.reshape(a, -1, copy=True)
    flat[0] = 99
    print(b.tolist())
    print(a.tolist())
    print(flat.tolist())

The original a keeps its values when flat changes. copy=True is required, even when the shape is unchanged; the result always owns separate storage. Only order='C' is supported. copy=False, copy=None, views, rank zero/three, method calls such as a.reshape(...), and F/A order are unsupported. A mismatched element count or ambiguous zero-size inference raises ValueError; bool/float dimensions raise TypeError. Empty arrays are allowed when the shape is unambiguous.

Totals and averages by column or row

Choose the direction using the existing axis argument. A matrix has rows and columns; the selected axis is the dimension reduced away.

axisResult for [[1,2,3],[4,5,6]]
None (default)One scalar: sum 21.0; mean 3.5.
0 or -2One value per column: sums [5.0,7.0,9.0]; means [2.5,3.5,4.5].
1 or -1One value per row: sums [6.0,15.0]; means [2.0,5.0].
*import numpy as np
def main():
    readings = np.array([[1, 2, 3], [4, 5, 6]], dtype="float64")
    print(np.sum(readings))
    print(np.sum(readings, axis=0).tolist())
    print(np.mean(readings, axis=1).tolist())

This prints 21.0, [5.0, 7.0, 9.0], then [2.0, 5.0]. Each axis result owns its storage; changing it leaves readings unchanged. The independent matrix starter exposes these operations as grids.totals and grids.averages. The same calls and contracts are available through headless engine/SDK authoring.

For a shape (0,3), sum with axis=0 returns three zero totals; mean with axis=0 raises ValueError because three empty averages are requested. Mean with axis=1 returns an empty vector because there are no rows. For (2,0), the directions reverse. Axis=None on any empty matrix returns zero for sum and raises ValueError for mean.

Reduction calls accept named a and axis arguments. Empty extrema and required empty mean slices raise ValueError; empty sum returns +0.0. No automatic sequence conversion, axis tuples, dtype, 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.

Weighted vector scoring

Use dot for bounded vector scoring. The SDK also offers an independent weighted-vector starter with its own namespace. Products round separately before pairwise summation. Different NumPy/BLAS accumulation can produce different results, especially under cancellation; package Help states the error bounds and finite-input limits.

*import numpy as np
def main():
    features=np.array([2,4,8],dtype="float64")
    weights=np.array([0.5,0.25,-0.5],dtype="float64")
    print(np.dot(a=features,b=weights))
    print(features.tolist())
    return 0

Output: -2.0, followed by [2.0, 4.0, 8.0].

*import numpy as np

def main():
    values = np.array([2, 4, 6, 8], dtype="float64")
    total = np.sum(values)
    average = np.mean(a=values, axis=-1)
    print(total, average)
    print(np.sum(values - average))
    print(np.sum(np.zeros(0)))
    return 0

This prints 20.0 5.0, then 0.0 and 0.0. Sum and mean split each range into two halves and combine their totals in a fixed order. They require binary64 nearest rounding and gradual underflow. A zero total becomes +0.0; mean division can underflow to signed zero. Mean supports lengths through 2**53. NumPy may choose another reduction order, so last-bit agreement is not promised. Cancellation can produce large relative error: for [1e16, -1e16, 1], this fixed tree returns a total of 0.0 rather than the exact mathematical 1.0. The bundled package Help describes the absolute error bounds. Non-nearest rounding raises RuntimeError; resource exhaustion retains the fatal Runtime policy.

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.

Matrix feature transforms

For weighted feature projections, matvec applies a matrix to a vector and vecmat applies vector weights across matrix rows:

*import numpy as np
def main():
    samples = np.array([[1, 2, 3], [4, 5, 6]], dtype="float64")
    weights = np.array([1, 0, 1], dtype="float64")
    scores = np.matvec(samples, weights)
    print(scores.tolist())
    print(np.vecmat(scores, samples).tolist())
    return 0

The SDK's Linear maps and transpose copies starter also provides transpose_copy(a). It copies a matrix of shape (m,n) into independent row-major storage of shape (n,m); a vector retains its shape in independent storage. Signed zeros and subnormals are preserved, and edits to the result leave the source unchanged. This is a separately named conversion operation. The bundled NumPy package does not expose transpose_copy, transpose or .T view syntax.

*import numpy as np

def main():
    samples = np.array([[1, 2, 3], [4, 5, 6]], dtype="float64")
    weights = np.array([[1, 0], [0, 1], [1, -1]], dtype="float64")
    scores = np.matmul(samples, weights)
    print(scores.tolist())
    print(np.sum(scores, axis=0).tolist())
    return 0

This prints [[4.0, -1.0], [10.0, -1.0]] and [14.0, -2.0]. The inputs remain unchanged. Each output uses the vector-dot numerical contract, including its absolute-error bound; NumPy/BLAS may use a different accumulation order. See the selected package Help for the full bounds and resource policy.

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.

Delimited records

Declare *import csv in Runtime mode. The bounded CSV package supplies reader(iterable, /, *, delimiter=',', quotechar='"', skipinitialspace=False, strict=False) and writer(file, /, *, delimiter=',', quotechar='"', lineterminator='\r\n'). A slash marks positional-only input; parameters after the star are keyword-only. Readers yield new lists of strings and expose read-only line_num. Writers expose writerow(row, /), returning characters written, and writerows(rows, /), returning None.

*import csv

def main():
    rows = csv.reader(['name,value\n', '"north,west",12\n'])
    print(next(rows), rows.line_num)
    print(next(rows), rows.line_num)
    with open("records.csv", "w", encoding="utf-8", newline="") as output:
        writer = csv.writer(output, lineterminator="\n")
        writer.writerow(["name", "value"])
        writer.writerows([["north,west", 12], ["south", 15]])
    return 0

The example prints the header at line 1 and the quoted station name at line 2, then writes three rows. Use UTF-8 text files with newline="". Reader input items represent physical lines; quoted fields can span lines. Delimiter and quotechar must be distinct single ASCII characters other than NUL, CR or LF. Quoting is minimal with doubled quotes; writer line endings are CRLF or LF.

Fields admit strings, int64, finite float64, bool and None (an empty field). A field is limited to 131072 Unicode scalars, a row to 16384 fields and input/output record text to 1 MiB of UTF-8; Runtime work and allocation budgets also apply. Format errors raise ValueError with line and column; wrong input types raise TypeError. This profile does not export csv.Error. line_num counts consumed items, including non-string items, which differs from CPython's error behavior.

Readers and writers retain their source/file and share state through aliases. They never close the caller's file; keep use inside its with block. Malformed partial rows are discarded without rewinding input. Formatting finishes before each row is written; earlier rows and partial I/O on device failure are not rolled back. Dialect registries, escape/quoting modes, DictReader/DictWriter, Sniffer, bytes, callbacks and custom conversion hooks are outside this profile. Import Help contains the full contract.

Bundled lazy iterators

Declare *import itertools as it in Runtime mode. The bounded 0.1.0 package supplies chain, islice and pairwise. Their constructors consume no records. Chain accepts zero through eight positional inputs and reaches later inputs lazily. Islice accepts (iterable, stop), (iterable, start, stop), or (iterable, start, stop, step). Pairwise accepts one input and yields overlapping two-item tuples. Keywords and argument expansion are unsupported.

*import itertools as it
def main():
    records = it.chain([10, 12], [15, 21])
    selected = it.islice(records, 1, None)
    for before, after in it.pairwise(selected):
        print(after - before)
    return 0

This prints 3 and 6. Inputs may be supported sequences, dictionaries/views, sets, owned vectors, text files or Runtime iterators. The pipeline retains references; aliases share one consumption position. Exhaustion releases retained references and is permanent. Files remain owned by the caller: keep the with block open while consuming them. No full input or result is copied.

Slice bounds are nonnegative signed int64 or None; step is positive or None. Fully consuming a finite slice advances its input by up to max(start, stop), irrespective of step. Positions do not wrap. CPython 3.12 can yield an extra item when an unbounded slice index plus step overflows signed int64; this profile follows non-wrapping positions instead. Custom iteration hooks, generators, callbacks, chain.from_iterable and other itertools operations are outside this subset. Import Help gives the complete error, ownership and resource rules.

The SDK's Lazy record pipelines starter exposes these same three kernels under an independent namespace, with editable export names, operation choices, complete Help and conversion fixtures. It does not yet admit author-written iterator state machines.

SDK author workflow

Use templates to choose a starter. Array, structured-value, text and iterator 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 successfully converted fixture containing that operation.

Conversion verification binds the saved project, documentation, fixtures, engine and SDK. Runtime expectations remain author declarations and are not evaluated by the SDK. 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. Verify conversions records conversion acceptance and expected rejections without running programs. The SDK invokes no C compiler; PyCForge owns Crucible/C compilation compatibility. The installed authoring.json follows authoring.schema.json and supplies the versioned data contract.