WireViz Python API

Use WireViz 0.4.1 parse(), return diagrams and resolved harnesses, generate files, resolve images, and handle mutable data and cached output safely.

The native Python API accepts YAML text, an input path, or an already-loaded dictionary. Its main entry point is wireviz.wireviz.parse. Use the pinned library if you need the behavior documented here. The browser editor runs a separate adapter around this engine; it does not expose a Python prompt or these native filesystem APIs. WireViz 0.4.1 parse source.

Return a resolved harness

from pathlib import Path
from wireviz import wireviz

harness = wireviz.parse(
    Path("harness.yml"),
    return_types="harness",
    image_paths=[],
)

print(list(harness.connectors))
print(list(harness.cables))
for row in harness.bom():
    print(row["description"], row["qty"], row.get("unit"))

The resolved maps contain instantiated designators, including generated instances. They are not the original YAML definition mappings. Requesting a harness alone does not write output files. Rendering SVG or PNG requires the native Graphviz executable in addition to the Python package.

Parse parameters

Parameter	Purpose
`inp`	A `Path`, a filename string, YAML source text, or a Python dictionary.
`return_types`	`"harness"`, `"svg"`, `"png"`, or a tuple of these; default none.
`output_formats`	File formats to generate; use a tuple such as `("svg", "tsv")`. Default none.
`output_dir`	Output directory; defaults to input-file directory, or current directory for source/dictionary input.
`output_name`	Basename without extension. Inferred from file input; required for file output from source/dictionary input.
`image_paths`	Additional image search directories. Pass a fresh list of strings or `Path` objects.

At least one of return_types or output_formats must be requested. Use full format names in Python, unlike the CLI's single-letter format string. For file outputs, use a tuple even for one format, such as ("svg",): the 0.4.1 implementation passes this value to code that iterates formats, so a bare string is not a reliable substitute despite the broad docstring wording.

A string input is first tested as a path to an existing file, then treated as YAML text if path resolution fails in the handled ways. Pass a Path for intentional file input and validate file existence in your application when useful; this avoids relying on ambiguous string interpretation.

Return multiple results

from pathlib import Path
from wireviz import wireviz

svg_text, png_bytes, harness = wireviz.parse(
    Path("harness.yml"),
    return_types=("svg", "png", "harness"),
    image_paths=[],
)

Path("preview.svg").write_text(svg_text, encoding="utf-8")
Path("preview.png").write_bytes(png_bytes)

Return values follow the requested order. SVG is a Unicode string; PNG is bytes; harness is the resolved Python object. One recognized return result is returned directly rather than wrapped in a tuple, even if requested in a one-element tuple. Use supported return names explicitly; this release does not provide exhaustive validation of unknown names.

Generate native output files

from pathlib import Path
from wireviz import wireviz

output = Path("build")
output.mkdir(parents=True, exist_ok=True)

wireviz.parse(
    Path("harness.yml"),
    output_formats=("gv", "svg", "html", "tsv"),
    output_dir=output,
    output_name="sensor-rev-a",
    image_paths=[Path("shared-assets")],
)

Supported implemented file formats are gv, html, png, svg, and tsv. CSV and PDF names appear in a docstring but are not implemented in the output routine. HTML generation uses the metadata/template system. If a custom template requests an embedded PNG, also generate PNG output so the referenced file exists.

The input file's parent directory is added to image search paths. A fresh list avoids shared mutable defaults and lets your integration control asset lookup. Keep uploaded web assets and native filesystem paths separate if building an adapter.

Dictionaries are consumed as mutable data

from copy import deepcopy
from wireviz import wireviz

document = {
    "connectors": {"X1": {"pincount": 2}},
    "connections": [["X1"]],
}

harness = wireviz.parse(
    deepcopy(document),
    return_types="harness",
    image_paths=[],
)

When given a dictionary, parse uses it directly. It can add missing sections, expand and rewrite connection entries, and resolve image paths. Deep-copy reusable application data before passing it in. Parsing a YAML string gives the library its own loaded structure and leaves the string unchanged.

Do not use a resolved harness as a source-preserving editor model. YAML comments, formatting, anchors, and template declarations are not recoverable from the resolved object in their original form. Keep the source separately and recompile after edits.

Lower-level Harness methods

The library also exposes methods on its Harness object. They are useful for integrations but are a lower-level interface than YAML parsing. Harness source.

Member	Purpose
`add_connector(name, **properties)`	Add an actual connector with the Connector dataclass fields.
`add_cable(name, **properties)`	Add an actual cable with the Cable dataclass fields.
`connect(from_name, from_pin, via_name, via_wire, to_name, to_pin)`	Join endpoints through a cable conductor, resolving normal pin/wire references. `None` endpoints can represent open ends.
`add_mate_pin(...)`	Add a pin-level mating arrow using actual pin IDs.
`add_mate_component(...)`	Add a whole-component mating arrow.
`add_bom_item(item)`	Add an independent BOM item mapping.
`create_graph()`	Build a Graphviz graph.
`graph`	Access the cached Graphviz graph.
`svg` / `png`	Render an SVG string or PNG bytes.
`bom()`	Return the generated BOM rows.
`output(filename, view=False, cleanup=True, fmt=(...))`	Write native output files using a path/basename and format tuple.

Graph and BOM results are cached. Mutation methods do not provide a general transaction or automatic cache-invalidation contract. Build and populate a harness before rendering, or parse a fresh harness after changing the input. Keep source validation, asset permissions, resource limits, and error reporting in the calling application when exposing the library as a service.