Add stdin/stdout streaming (port of upstream PR #321)

[SomethingNew71]

Summary

Ports upstream PR #321 (originally targeting upstream dev) to our master-derived upstream-fixes branch, enabling the WireViz CLI to participate in unix pipelines.

This is the highest-value PR for the upcoming wireviz-gui work — the GUI can pipe YAML in and get rendered SVG/PNG out without temp files.

Usage

# YAML in, SVG out
cat harness.yml | wireviz -f s -O - -    > harness.svg

# YAML in, PNG out (binary)
cat harness.yml | wireviz -f p -O - -    > harness.png

# File in, HTML out
wireviz -f h -O - harness.yml             > harness.html

• Pass - as the input filename to read YAML from stdin.
• Pass - to either --output-dir or --output-name to write to stdout.
• Exactly one format may be requested when writing to stdout (multi-format → stdout is rejected with a clear error).

Implementation

Two refactors enable the streaming path while keeping file mode bit-for-bit unchanged:

1. Harness.output() → Harness._render() + dispatch. A new _render(fmt) returns an in-memory {format: bytes|str} dict by piping graphviz directly (graph.pipe(format=...)) and calling embed_svg_images() on the SVG string. The old code rendered to a temporary .tmp.svg file, embedded images via embed_svg_images_file(), then renamed/deleted the temp. That dance is gone — embed_svg_images_file is dropped as unused.

2. generate_html_output() takes the SVG as a string and returns the HTML string instead of reading a temp file and writing the .html file itself. New output_dir / output_name / png_b64 / source_path parameters preserve <!-- %filename% -->, <!-- %filename_stem% -->, and <!-- %diagram_png_b64% --> placeholders in file mode (and leave them empty/unresolved in stdout mode).

Library-level print() warnings in DataClasses.py, Harness.py, wv_colors.py, wv_helper.py, and wireviz.py are routed to sys.stderr so stdout stays clean of log noise when piped. CLI status banners in wv_cli.py go to stderr for the same reason.

Differences from upstream PR wireviz#321

• Adapted to current master's file_read_text / file_write_text helpers (the upstream PR was written against the older open_file_read / open_file_write API).
• Integrated cleanly with #473's source_path template-search additions (already on upstream-fixes) — generate_html_output() now takes a source_path parameter and the search order is source-dir → output-dir → built-in templates.
• Keeps file-mode <!-- %diagram_png_b64% --> working by reading from the just-rendered PNG; in stdout mode the placeholder is unresolved (rare edge case).

Verification

• build_examples.py runs cleanly across all 14 examples + 8 tutorials + 2 demos.
• Deterministic outputs (.gv, .bom.tsv) are byte-identical to baseline → no behavior change in file mode.
• Tested stdin→stdout for SVG (text, 15KB) and PNG (binary, valid 1086×401 RGBA).
• Multi-format-to-stdout correctly rejected with a clear error.

Test plan

• cat examples/demo01.yml | wireviz -f s -O - - > /tmp/out.svg produces a valid SVG
• cat examples/demo01.yml | wireviz -f p -O - - > /tmp/out.png produces a valid PNG
• CI workflow passes across Python 3.7–3.12
• Smoke-test from the GUI prototype side (when available)

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request refactors the output generation logic to support stdin/stdout piping and in-memory rendering, while also redirecting warnings and errors to stderr. Key improvements include the introduction of an internal _render method and updated HTML generation that supports inlined base64 images. Review feedback suggests refining the type-hinting and normalization of output formats, correcting a regression in image path resolution to ensure relative paths are resolved against the source file directory, and improving code quality by using specific exception types and standardizing import placements.

[gemini-code-assist]

The fmt parameter is type-hinted as a tuple, but the wireviz.parse function allows it to be a single string. If a string is passed, the subsequent loop for f in fmt: will iterate over its characters instead of the intended format names. It is recommended to allow Union[str, tuple, list] and normalize it to a collection.

Suggested change

	fmt: tuple = ("html", "png", "svg", "tsv"),
	fmt: Union[str, tuple, list] = ("html", "png", "svg", "tsv"),

[gemini-code-assist]

Normalize the fmt parameter to a tuple if a single string is provided to ensure correct iteration in the following steps.

        if isinstance(fmt, str):
            fmt = (fmt,)
        outputs: Dict[str, Union[str, bytes]] = self._render(
            fmt,
            output_dir=output_dir,
            output_name=output_name,
        )

[gemini-code-assist]

Using Path.cwd() as the base path for image resolution is a regression for file-based output. Images should be resolved relative to the source YAML file's directory when available. This ensures that relative image paths in the harness definition work correctly regardless of the current working directory.

        svg_str: Optional[str] = None
        if "svg" in fmt or "html" in fmt:
            base_path = Path(self.source_path).parent if self.source_path and str(self.source_path) != "-" else Path.cwd()
            svg_str = embed_svg_images(
                graph.pipe(format="svg").decode("utf-8"), base_path
            )

[gemini-code-assist]

The base64 import should be moved to the top of the file to adhere to PEP 8 style guidelines, which recommend placing all imports at the beginning of the module.

Suggested change

	import sys
	import re
	import sys
	import base64
	from collections import Counter

[gemini-code-assist]

Update the type hint for fmt to include str and list for consistency with the output method and the wireviz.parse API.

Suggested change

	fmt: tuple,
	fmt: Union[str, tuple, list],

[gemini-code-assist]

The base64 import should be at the top of the file. This local import can be removed.

Suggested change

	import base64
	graph = self.graph
	graph = self.graph

[gemini-code-assist]

Avoid raising a generic Exception. A more specific exception like ValueError is preferred here as it clearly indicates that the provided arguments are invalid for the requested operation.

Suggested change

	raise Exception(
	"Exactly one output format must be specified when writing to stdout."
	)
	if len(output_formats) != 1:
	raise ValueError(
	"Exactly one output format must be specified when writing to stdout."
	)

[gemini-code-assist]

In a Click-based CLI, it is better to raise click.UsageError or click.ClickException instead of a generic Exception. This allows Click to handle the error gracefully and display a user-friendly message.

Suggested change

	raise Exception(
	"Exactly one output format (-f) must be specified when writing to stdout."
	)
	raise click.UsageError(
	"Exactly one output format (-f) must be specified when writing to stdout."
	)

[SomethingNew71]

@ggrossetie — heads up, your upstream #321 (stdin/stdout streaming) is being incorporated here.

Context: We use WireViz to document Classic Mini Cooper wiring harnesses at Classic Mini DIY and are building a GUI front-end. Upstream wireviz/WireViz looks abandoned (last real master commit was 2021, the dev refactor has been sitting unreleased for over a year), so we're forking and pulling in the open PRs we want.

Your stdin/stdout PR is the single most consequential one for our GUI direction — it lets the front-end pipe YAML in and rendered SVG/PNG out without temp files. The port adapts the patch to current master since your PR was originally against dev and pre-dates the file_read_text / file_write_text rename. The core ideas (in-memory render dict, dropping the .tmp.svg roundtrip, routing log output to stderr) are preserved. Commit attribution links back to your PR.

Two small adaptations worth flagging:

• generate_html_output was reworked to also accept source_path, template_dir, and png_b64 — those are integrating with other PRs we're pulling in (Fix template search path wireviz/WireViz#473, Add support for a custom template directory path wireviz/WireViz#444). Doesn't change the load-bearing parts of your design.
• A reviewer caught a couple of refinements which are folded in: fmt accepts Union[str, tuple, list] with str-normalization, base64 import moved to module top, and click.UsageError for the multi-format-to-stdout check.

Thanks for the work — really appreciate it.