onnx_light.doc#

class onnx_light.doc.InferenceCaseReport(name: str, model_str: str, error: str | None, comparisons: list[ValueComparison] = <factory>)#

Shape-inference outcome for one "inference"-tagged test case.

comparisons: list[ValueComparison]#: One ValueComparison per input, intermediate (value_info) and output value of the model. Empty when error is set.

error: str | None#: Error message raised by infer_shapes_model(), or None when shape inference succeeded.

model_str: str#: Compact text rendering of the original model (with its expected value_info annotations), produced by pretty_onnx().

name: str#: Name of the backend test case (e.g. "test_cc_shape_inference_add_concat_reshape").

property ok: bool#: True when shape inference completed and every comparison matches.

class onnx_light.doc.InferenceCoverageReport(cases: list[InferenceCaseReport] = <factory>)#: Aggregates InferenceCaseReport for every collected case.

class onnx_light.doc.ValueComparison(name: str, role: str, expected: ValueShape | None, computed: ValueShape | None)#

Per-value comparison of expected vs computed shape.

computed: ValueShape | None#: Shape produced by infer_shapes_model(), or None when shape inference produced no entry for that value.

expected: ValueShape | None#: Shape recorded in the original test model, or None when the value has no expected shape (for instance an intermediate without a value_info entry).

property match: bool#

Returns whether expected and computed agree.

A value with no expected shape (expected is None) is considered to match by convention so that intermediate values without a value_info entry do not flag the case as failing. Otherwise both the element type and the shape must be equal.

name: str#: Name of the value (graph input, value_info or graph output).

role: str#: "input", "value_info" or "output".

class onnx_light.doc.ValueShape(elem_type: int | None, shape: list[int | str | None] | None)#

Shape / element type of a single tensor value (input, intermediate or output) in a backend test model.

A shape entry is None when the corresponding ValueInfoProto has no type set (so the value is opaque to shape inference). Dimensions are encoded as either int (dim_value), str (dim_param) or None (unknown dimension).

elem_type: int | None#: ONNX TensorProto.DataType enum value, or None when the value has no tensor type.

shape: list[int | str | None] | None#: One entry per dimension or None when the value has no tensor shape set.

onnx_light.doc.compute_inference_coverage() → InferenceCoverageReport#

Computes the shape-inference report for every "inference" case.

For every case, the model is deep-cloned, its graph.value_info is cleared, and infer_shapes_model() (from onnx_shapes) is run on the clone. The report contrasts the expected shapes from the original model with the computed shapes from the inferred clone.

Locates a standalone executable built from repository examples.

Parameters:

executable_name – Name used for PATH lookup fallback.
relative_candidates – Candidate executable paths relative to repository root.
script_file – Path to the calling script file used to locate repository root. The repository root is assumed to be three parent directories above this path.
windows_build_configs – Optional Windows build configuration folder names.
reason_out – Optional list that, when provided, receives a human-readable string describing why the executable could not be located when this function returns None. Useful for surfacing the cause (CI mode, missing build artifacts, not on PATH) in user-facing diagnostics.

Returns:

The discovered executable path. Returns None when the CI environment variable is enabled (unless CICPP is also enabled to opt back in), or when no candidate file exists and PATH lookup does not find the executable.

onnx_light.doc.generate_operators_doc(output_dir: str, progress_callback: Callable[[str], None] | None = None) → None#

Generates operator RST pages into output_dir.

Reads all ONNX operator schemas from the lightweight onnx_op C extension (LightOpSchema) and writes one RST file per domain plus a top-level index.rst toctree.

Parameters:

output_dir – Directory where the generated .rst files are written. It is created if it does not already exist.
progress_callback – Optional callback receiving progress messages while pages are generated.

onnx_light.doc.get_cpu_topology() → dict[str, int | None]#

Returns CPU topology information.

The returned mapping contains:

logical: number of logical processors (threads) available, or None if it cannot be determined.
physical_cores: total number of physical cores across all sockets, or None if it cannot be determined.
sockets: number of physical processors (sockets), or None if it cannot be determined.

On Linux, /proc/cpuinfo is parsed to derive physical core and socket counts. On other platforms (or when /proc/cpuinfo is unavailable), only the logical processor count from os.cpu_count() is reported.

onnx_light.doc.get_processor_name() → str#: Returns a human-readable processor name, falling back to platform data.

onnx_light.doc.get_total_memory_gb() → float | None#: Returns total system memory in GB, or None if it cannot be determined.

onnx_light.doc.measure_cpp_with_example(executable: str | None, args: list[str], metric_pattern: Pattern[str], result_name: str, executable_name: str) → dict | None#

Runs a standalone C++ benchmark executable and parses its timing output.

Parameters:

executable – Path to the C++ executable, or None if unavailable.
args – Arguments passed to the executable (not including the executable itself).
metric_pattern – Compiled regex pattern to match metric lines in stdout. Must capture the metric label in group 1 and the numeric value in group 2. The captured label must produce "average", "median", "min", and "max" (case-folded) for the four required metrics, and may also produce "std" or "standard deviation".
result_name – Benchmark name stored in the returned dictionary’s name key.
executable_name – Human-readable executable name used in diagnostic messages.

Returns:

A benchmark dictionary with keys name, median, avg, min, max, and std if successful, otherwise None.

onnx_light.doc.render_rst_case(case: InferenceCaseReport) → str#

Renders one test case as a reST section.

The section contains:

a .. code-block:: text block rendering the original model via pretty_onnx();
either an error admonition (when shape inference raised) or a list-table contrasting expected and computed shapes for every input, intermediate and output value.

onnx_light.doc.render_rst_report(report: InferenceCoverageReport) → str#: Renders every collected case back-to-back.

onnx_light.doc.render_rst_summary(report: InferenceCoverageReport) → str#: Renders a one-row summary as a reST list-table.