archgraph-layout 1.0.0__tar.gz

archgraph_layout-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ellie Hartung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

archgraph_layout-1.0.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md LICENSE pyproject.toml MANIFEST.in
+recursive-include archgraph *.py
+include docs/xml-reference.md
+recursive-include examples *.xml
+prune gallery
+prune tests
+prune .git
+prune .pytest_cache
+prune .venv
+prune build
+prune dist
+prune .release-check
+global-exclude __pycache__ *.py[cod] .DS_Store Thumbs.db

archgraph_layout-1.0.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: archgraph-layout
+Version: 1.0.0
+Summary: Hierarchical architecture diagrams from XML with floorplanning and orthogonal routing
+Author: Ellie Hartung
+License-Expression: MIT
+Keywords: architecture,diagrams,xml,layout,floorplanning,svg
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23.5
+Requires-Dist: scipy>=1.9.3
+Provides-Extra: png
+Requires-Dist: playwright>=1.40; extra == "png"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6.1; extra == "dev"
+Dynamic: license-file
+
+# archgraph-layout
+
+**Hierarchical architecture diagrams from XML** — a Graphviz-style tool built for complex
+hardware and system diagrams. Instead of a layered (Sugiyama) layout that grows very tall
+or very wide, archgraph **floorplans** each subsystem, the way VLSI tools place blocks
+on a die. The result fits a target aspect ratio, groups blocks by subsystem, and keeps
+signal flow readable. Wires are routed orthogonally, with real port handling, nets and
+buses.
+
+```
+python -m archgraph render examples/soc.xml -o soc.svg -o soc.html
+```
+
+* Pure Python (numpy + scipy). Output: **SVG**, an **interactive HTML** viewer
+  (pan/zoom/search/highlight), **JSON** layout data, and optionally **PNG** (via Playwright).
+* Deterministic: the same input and seed always give the same drawing.
+
+## Installation
+
+Requires Python 3.10 or newer. Install from PyPI after publication:
+
+```sh
+python -m pip install archgraph-layout
+```
+
+The Python import is `archgraph` and the command is `archgraph`:
+
+```sh
+archgraph --version
+archgraph render system.xml -o system.svg -o system.html
+```
+
+For example, save this as `system.xml`:
+
+```xml
+<archgraph title="My system">
+  <node id="cpu" label="CPU"/>
+  <node id="memory" label="Memory"/>
+  <edge from="cpu" to="memory"/>
+</archgraph>
+```
+
+For optional PNG export, install the extra and Chromium:
+
+```sh
+python -m pip install "archgraph-layout[png]"
+python -m playwright install chromium
+```
+
+The source archive includes the XML examples and reference. Generated gallery
+previews and development files are excluded from the published packages.
+
+---
+
+## Contents
+
+1. [How the engine works](#how-the-engine-works)
+2. [Command line](#command-line)
+3. [Python API](#python-api)
+4. [XML reference](docs/xml-reference.md)
+5. [Tuning](#tuning)
+6. [Examples](#examples)
+7. [Testing](#testing)
+
+---
+
+## How the engine works
+
+```
+XML ──► parse/expand ──► size blocks ──► auto-cluster huge levels
+    ──► hierarchical floorplanning (bottom-up, several passes)
+    ──► detailed QP placement + edge alignment (bottom-up, then top-down)
+    ──► port sides (router-chosen) ──► orthogonal routing ──► congestion-driven spacing
+    ──► nudging ──► labels ──► SVG / HTML / JSON / PNG
+```
+
+**Floorplanning (placement).** Each subsystem level is a floorplanning problem over
+its direct children. A child can be a leaf block or a subsystem that was already
+laid out. Topologies are encoded as **sequence pairs** and explored by **simulated
+annealing**. The cost combines:
+
+| term | what it measures |
+|---|---|
+| area, aspect | packing density; deviation from the target width/height (steeper at the top level) |
+| wire | weighted Manhattan length between *pins*: the exact deep port positions inside children |
+| flow | edges running against the subsystem's direction (backward edges cost more than sideways ones) |
+| bend | connections whose ends cannot be aligned without a bend |
+| crossing / through | straight-line crossings, and wires passing through other blocks (routing proxies) |
+| terminal | connections leaving the subsystem pull towards the side facing their partner |
+| order | repeated instances (core0, core1, …) read in declaration order |
+| hints | your guidance (see [Layout hints](docs/xml-reference.md#layout-hints)) |
+
+Child subsystems contribute several **shape variants** (natural, square, wide, tall).
+The annealer picks one per child, and can also mirror a child perpendicular to its
+flow. Initial states come from a Sugiyama layout (LP layering, barycentre ordering,
+VPSC coordinates, aspect-driven band wrapping), a spectral (Fiedler) grid order, warm
+starts from the previous pass, and random states. Tiny levels (≤ 4 blocks) are solved
+exhaustively. Identical template instances are solved once and drawn identically.
+
+**Detailed placement.** The annealer gives each level a topology; a convex QP then
+computes exact coordinates. The QP is solved by gradient projection over a **VPSC**
+separation-constraint solver. It straightens wires, compacts, and enforces non-overlap,
+containment and your hard hints. A greedy **HOLA-style** pass then adds equality
+constraints so that nearly straight connections become exactly straight. A top-down
+pass re-solves every level with the real positions of external partners.
+
+**Routing.** All wires are routed orthogonally on a sparse non-uniform grid, using an
+A* search that knows each wire's direction. Costs cover length, bends, crossings,
+channel sharing, corridor overflow, passing other ports, wall proximity (wires prefer
+channel centres), turning close to a wall, and crossing subsystem borders. Crossing
+the border of a subsystem that contains neither end is almost forbidden. Specifics:
+
+* Ports have a **straight escape** (about 20px) before the first turn.
+* A first pass routes with **floating ports**, so each automatic port attaches on the side its
+  wire arrives from.
+* Edges sharing a declared port form one **net**, drawn as a Steiner tree with junction dots.
+  **Buses** become trunk trees.
+* **PathFinder** negotiation rips up and reroutes congested nets.
+* **Congestion-driven spacing.** Gaps that carry more wires than fit comfortably are widened,
+  overloaded blocks grow, and the layout is re-compacted (same topology) and rerouted.
+* **Nudging** (VPSC again) spreads overlapping wires into parallel tracks. It orders them to
+  avoid crossings, keeps them clear of blocks and titles, and centres bundles in their corridor.
+  Every port's escape stub is a keep-out zone, so no wire is squeezed in under an arrowhead.
+* **Crossings** (`crossings="hop"`, the default; or `"gap"` / `"none"`). Hops are drawn in a
+  layer above every wire, with a halo in the local background colour, so nothing is ever
+  painted over a hop. Crossings closer together than one hop share a single flat bridge.
+  Each hop bumps to the side where the crossed wire has room (clear of its arrowheads,
+  corners and neighbouring parallel wires). A crossing right next to a corner of the
+  horizontal wire hops sideways on the vertical wire instead. Bit-width markers and edge
+  labels keep clear of crossings.
+
+---
+
+## Command line
+
+```
+archgraph render  FILE.xml [-o OUT.svg|.html|.json|.png ...] [--stats]
+                  [--quality draft|normal|high|max] [--aspect 16:9] [--theme dark]
+                  [--direction TB] [--seed N] [--set key=value ...]
+archgraph validate FILE.xml        # parse, report errors (with line numbers) and warnings
+archgraph stats    FILE.xml        # lay out and print quality metrics as JSON
+archgraph expand   FILE.xml        # print the XML after templates/loops/includes expand
+archgraph FILE.xml -o out.svg      # shorthand for render
+```
+
+`--stats` reports blocks, aspect, crossings, bends, wire length, overlaps, containment
+violations, wires through blocks, wire length hugging walls, minimum port escape,
+flow-consistency counts and timings.
+
+## Python API
+
+```python
+import archgraph
+
+g = archgraph.build("system.xml", aspect="4:3", quality="high")  # parse + layout + route
+archgraph.save(g, "system.svg")        # format by extension: .svg .html .json .png
+svg = archgraph.to_svg(g)
+
+g = archgraph.loads(xml_text)            # or step by step
+archgraph.layout(g); archgraph.route(g)
+for n in g.nodes(): print(n.id, n.x, n.y, n.w, n.h)
+from archgraph.quality import metrics; print(metrics(g))
+```
+
+---
+
+## XML reference
+
+See the [standalone XML reference](docs/xml-reference.md) for a starter diagram,
+settings and defaults, nodes and ports, edges and buses, layout hints, styles,
+templates, loops, includes, and validation guidance.
+
+---
+
+## Tuning
+
+* **Shape**: `aspect` (global) and per-subsystem `aspect`. The top level weights aspect most.
+* **Compactness vs readability**: `<weights area="0.6" wire="2.4" flow="3" crossing="1.4" through="1.4"
+  bend="1.6" terminal="1.4" order="1.6" aspect="2.2" hint_hard="10" hint_soft="2.5"/>`.
+* **Effort**: `quality="high"` adds an annealing pass, longer schedules and more spacing iterations.
+* **Room for wires**: `node-spacing`, `subsystem-padding`, `edge-spacing`, `node-margin`.
+* **Big flat graphs**: `max-level-items` and `auto-group="visible"` (shows the clusters found).
+* **Hard vs soft hints**: `left-of`/`above`/`row`/`column`/`order` are hard: the floorplanner
+  only considers arrangements that keep them, and a subsystem shape that would break them
+  is never offered to the parent. `near`/`place`/`anchor` are soft preferences.
+* **Port sides** are chosen from geometry (facing the partner, flow, blocked sides) and then
+  refined by a trial routing pass that may move a port to another side when the wire is
+  clearly better there; sides facing away from the partner are strongly discouraged.
+  Pin a side explicitly with `side=` on a `<port>` or `from="a@north"`.
+
+## Examples
+
+| file | shows |
+|---|---|
+| `examples/basic.xml` | small starter |
+| `examples/soc.xml` | mobile SoC: big.LITTLE templates, NoC hubs, buses, notes, hints, legend, title block |
+| `examples/accelerator_mesh.xml` | 64-tile mesh accelerator, ~200 blocks (nested repeats, grid, uniform instances) |
+| `examples/datacenter.xml` | spine/leaf fabric, racks, storage, dark theme |
+| `examples/automotive.xml` | zonal E/E architecture, CAN/Ethernet buses, TB flow |
+| `examples/fpga_pipeline.xml` | DSP datapath with mux/register/adder shapes, layered algorithm |
+| `examples/flat_network.xml` | 150+ blocks without subsystems: automatic clustering |
+
+## Testing
+
+```
+python -m pip install -e ".[dev]"
+python -m pytest tests -q
+```
+
+The suite covers the VPSC solver (checked against SLSQP and KKT conditions, including
+infeasible systems), the XML language, floorplanning and placement invariants (no
+overlaps, containment, hint satisfaction, aspect), routing invariants (orthogonality,
+connectivity, no wires through blocks, port escape, clearance), rendering, the CLI, and
+end-to-end quality metrics for every example.
+
+## License and author
+
+MIT License. Copyright (c) 2026 Ellie Hartung. See [LICENSE](LICENSE).
+
+For release instructions, see [Publishing](docs/publishing.md) in the checkout.

archgraph_layout-1.0.0/README.md

@@ -0,0 +1,220 @@
+# archgraph-layout
+
+**Hierarchical architecture diagrams from XML** — a Graphviz-style tool built for complex
+hardware and system diagrams. Instead of a layered (Sugiyama) layout that grows very tall
+or very wide, archgraph **floorplans** each subsystem, the way VLSI tools place blocks
+on a die. The result fits a target aspect ratio, groups blocks by subsystem, and keeps
+signal flow readable. Wires are routed orthogonally, with real port handling, nets and
+buses.
+
+```
+python -m archgraph render examples/soc.xml -o soc.svg -o soc.html
+```
+
+* Pure Python (numpy + scipy). Output: **SVG**, an **interactive HTML** viewer
+  (pan/zoom/search/highlight), **JSON** layout data, and optionally **PNG** (via Playwright).
+* Deterministic: the same input and seed always give the same drawing.
+
+## Installation
+
+Requires Python 3.10 or newer. Install from PyPI after publication:
+
+```sh
+python -m pip install archgraph-layout
+```
+
+The Python import is `archgraph` and the command is `archgraph`:
+
+```sh
+archgraph --version
+archgraph render system.xml -o system.svg -o system.html
+```
+
+For example, save this as `system.xml`:
+
+```xml
+<archgraph title="My system">
+  <node id="cpu" label="CPU"/>
+  <node id="memory" label="Memory"/>
+  <edge from="cpu" to="memory"/>
+</archgraph>
+```
+
+For optional PNG export, install the extra and Chromium:
+
+```sh
+python -m pip install "archgraph-layout[png]"
+python -m playwright install chromium
+```
+
+The source archive includes the XML examples and reference. Generated gallery
+previews and development files are excluded from the published packages.
+
+---
+
+## Contents
+
+1. [How the engine works](#how-the-engine-works)
+2. [Command line](#command-line)
+3. [Python API](#python-api)
+4. [XML reference](docs/xml-reference.md)
+5. [Tuning](#tuning)
+6. [Examples](#examples)
+7. [Testing](#testing)
+
+---
+
+## How the engine works
+
+```
+XML ──► parse/expand ──► size blocks ──► auto-cluster huge levels
+    ──► hierarchical floorplanning (bottom-up, several passes)
+    ──► detailed QP placement + edge alignment (bottom-up, then top-down)
+    ──► port sides (router-chosen) ──► orthogonal routing ──► congestion-driven spacing
+    ──► nudging ──► labels ──► SVG / HTML / JSON / PNG
+```
+
+**Floorplanning (placement).** Each subsystem level is a floorplanning problem over
+its direct children. A child can be a leaf block or a subsystem that was already
+laid out. Topologies are encoded as **sequence pairs** and explored by **simulated
+annealing**. The cost combines:
+
+| term | what it measures |
+|---|---|
+| area, aspect | packing density; deviation from the target width/height (steeper at the top level) |
+| wire | weighted Manhattan length between *pins*: the exact deep port positions inside children |
+| flow | edges running against the subsystem's direction (backward edges cost more than sideways ones) |
+| bend | connections whose ends cannot be aligned without a bend |
+| crossing / through | straight-line crossings, and wires passing through other blocks (routing proxies) |
+| terminal | connections leaving the subsystem pull towards the side facing their partner |
+| order | repeated instances (core0, core1, …) read in declaration order |
+| hints | your guidance (see [Layout hints](docs/xml-reference.md#layout-hints)) |
+
+Child subsystems contribute several **shape variants** (natural, square, wide, tall).
+The annealer picks one per child, and can also mirror a child perpendicular to its
+flow. Initial states come from a Sugiyama layout (LP layering, barycentre ordering,
+VPSC coordinates, aspect-driven band wrapping), a spectral (Fiedler) grid order, warm
+starts from the previous pass, and random states. Tiny levels (≤ 4 blocks) are solved
+exhaustively. Identical template instances are solved once and drawn identically.
+
+**Detailed placement.** The annealer gives each level a topology; a convex QP then
+computes exact coordinates. The QP is solved by gradient projection over a **VPSC**
+separation-constraint solver. It straightens wires, compacts, and enforces non-overlap,
+containment and your hard hints. A greedy **HOLA-style** pass then adds equality
+constraints so that nearly straight connections become exactly straight. A top-down
+pass re-solves every level with the real positions of external partners.
+
+**Routing.** All wires are routed orthogonally on a sparse non-uniform grid, using an
+A* search that knows each wire's direction. Costs cover length, bends, crossings,
+channel sharing, corridor overflow, passing other ports, wall proximity (wires prefer
+channel centres), turning close to a wall, and crossing subsystem borders. Crossing
+the border of a subsystem that contains neither end is almost forbidden. Specifics:
+
+* Ports have a **straight escape** (about 20px) before the first turn.
+* A first pass routes with **floating ports**, so each automatic port attaches on the side its
+  wire arrives from.
+* Edges sharing a declared port form one **net**, drawn as a Steiner tree with junction dots.
+  **Buses** become trunk trees.
+* **PathFinder** negotiation rips up and reroutes congested nets.
+* **Congestion-driven spacing.** Gaps that carry more wires than fit comfortably are widened,
+  overloaded blocks grow, and the layout is re-compacted (same topology) and rerouted.
+* **Nudging** (VPSC again) spreads overlapping wires into parallel tracks. It orders them to
+  avoid crossings, keeps them clear of blocks and titles, and centres bundles in their corridor.
+  Every port's escape stub is a keep-out zone, so no wire is squeezed in under an arrowhead.
+* **Crossings** (`crossings="hop"`, the default; or `"gap"` / `"none"`). Hops are drawn in a
+  layer above every wire, with a halo in the local background colour, so nothing is ever
+  painted over a hop. Crossings closer together than one hop share a single flat bridge.
+  Each hop bumps to the side where the crossed wire has room (clear of its arrowheads,
+  corners and neighbouring parallel wires). A crossing right next to a corner of the
+  horizontal wire hops sideways on the vertical wire instead. Bit-width markers and edge
+  labels keep clear of crossings.
+
+---
+
+## Command line
+
+```
+archgraph render  FILE.xml [-o OUT.svg|.html|.json|.png ...] [--stats]
+                  [--quality draft|normal|high|max] [--aspect 16:9] [--theme dark]
+                  [--direction TB] [--seed N] [--set key=value ...]
+archgraph validate FILE.xml        # parse, report errors (with line numbers) and warnings
+archgraph stats    FILE.xml        # lay out and print quality metrics as JSON
+archgraph expand   FILE.xml        # print the XML after templates/loops/includes expand
+archgraph FILE.xml -o out.svg      # shorthand for render
+```
+
+`--stats` reports blocks, aspect, crossings, bends, wire length, overlaps, containment
+violations, wires through blocks, wire length hugging walls, minimum port escape,
+flow-consistency counts and timings.
+
+## Python API
+
+```python
+import archgraph
+
+g = archgraph.build("system.xml", aspect="4:3", quality="high")  # parse + layout + route
+archgraph.save(g, "system.svg")        # format by extension: .svg .html .json .png
+svg = archgraph.to_svg(g)
+
+g = archgraph.loads(xml_text)            # or step by step
+archgraph.layout(g); archgraph.route(g)
+for n in g.nodes(): print(n.id, n.x, n.y, n.w, n.h)
+from archgraph.quality import metrics; print(metrics(g))
+```
+
+---
+
+## XML reference
+
+See the [standalone XML reference](docs/xml-reference.md) for a starter diagram,
+settings and defaults, nodes and ports, edges and buses, layout hints, styles,
+templates, loops, includes, and validation guidance.
+
+---
+
+## Tuning
+
+* **Shape**: `aspect` (global) and per-subsystem `aspect`. The top level weights aspect most.
+* **Compactness vs readability**: `<weights area="0.6" wire="2.4" flow="3" crossing="1.4" through="1.4"
+  bend="1.6" terminal="1.4" order="1.6" aspect="2.2" hint_hard="10" hint_soft="2.5"/>`.
+* **Effort**: `quality="high"` adds an annealing pass, longer schedules and more spacing iterations.
+* **Room for wires**: `node-spacing`, `subsystem-padding`, `edge-spacing`, `node-margin`.
+* **Big flat graphs**: `max-level-items` and `auto-group="visible"` (shows the clusters found).
+* **Hard vs soft hints**: `left-of`/`above`/`row`/`column`/`order` are hard: the floorplanner
+  only considers arrangements that keep them, and a subsystem shape that would break them
+  is never offered to the parent. `near`/`place`/`anchor` are soft preferences.
+* **Port sides** are chosen from geometry (facing the partner, flow, blocked sides) and then
+  refined by a trial routing pass that may move a port to another side when the wire is
+  clearly better there; sides facing away from the partner are strongly discouraged.
+  Pin a side explicitly with `side=` on a `<port>` or `from="a@north"`.
+
+## Examples
+
+| file | shows |
+|---|---|
+| `examples/basic.xml` | small starter |
+| `examples/soc.xml` | mobile SoC: big.LITTLE templates, NoC hubs, buses, notes, hints, legend, title block |
+| `examples/accelerator_mesh.xml` | 64-tile mesh accelerator, ~200 blocks (nested repeats, grid, uniform instances) |
+| `examples/datacenter.xml` | spine/leaf fabric, racks, storage, dark theme |
+| `examples/automotive.xml` | zonal E/E architecture, CAN/Ethernet buses, TB flow |
+| `examples/fpga_pipeline.xml` | DSP datapath with mux/register/adder shapes, layered algorithm |
+| `examples/flat_network.xml` | 150+ blocks without subsystems: automatic clustering |
+
+## Testing
+
+```
+python -m pip install -e ".[dev]"
+python -m pytest tests -q
+```
+
+The suite covers the VPSC solver (checked against SLSQP and KKT conditions, including
+infeasible systems), the XML language, floorplanning and placement invariants (no
+overlaps, containment, hint satisfaction, aspect), routing invariants (orthogonality,
+connectivity, no wires through blocks, port escape, clearance), rendering, the CLI, and
+end-to-end quality metrics for every example.
+
+## License and author
+
+MIT License. Copyright (c) 2026 Ellie Hartung. See [LICENSE](LICENSE).
+
+For release instructions, see [Publishing](docs/publishing.md) in the checkout.

archgraph_layout-1.0.0/archgraph/__init__.py

@@ -0,0 +1,108 @@
+"""archgraph — hierarchical architecture diagrams with floorplanning layout and orthogonal routing.
+
+Typical use::
+
+    import archgraph
+    g = archgraph.build("system.xml")            # parse + layout + route
+    open("system.svg", "w").write(archgraph.to_svg(g))
+
+or from the command line::
+
+    archgraph render system.xml -o system.svg
+"""
+from __future__ import annotations
+
+import os
+import time
+from typing import Optional
+
+from .model import ArchGraphError, Graph
+from .parser import parse_file, parse_string
+# import subpackages eagerly so the public functions below are not shadowed by them
+from .placement import engine as _engine  # noqa: E402
+from . import routing as _routing  # noqa: E402
+
+__version__ = "1.0.0"
+__all__ = ["load", "loads", "layout", "route", "build", "to_svg", "to_html", "to_json", "to_png", "save",
+           "ArchGraphError", "Graph", "__version__"]
+
+
+def load(path: str) -> Graph:
+    """Parse an XML file into a :class:`Graph` (no layout yet)."""
+    return parse_file(path)
+
+
+def loads(text: str, base_dir: Optional[str] = None) -> Graph:
+    """Parse XML text into a :class:`Graph`."""
+    return parse_string(text, base_dir=base_dir)
+
+
+def layout(g: Graph) -> Graph:
+    """Place every block and subsystem (and assign ports)."""
+    _engine.layout(g)
+    return g
+
+
+def route(g: Graph) -> Graph:
+    """Route all connections and buses, nudge them apart and place labels."""
+    _routing.route(g)
+    from .geometry import Rect
+    rects = [e.rect for e in g.root.iter_descendants()]
+    g.bbox = Rect.bounding(rects)
+    return g
+
+
+def build(source: str, **overrides) -> Graph:
+    """Parse (file path or XML text), apply setting overrides, lay out and route."""
+    t0 = time.time()
+    if os.path.exists(source) or source.lower().endswith(".xml"):
+        g = parse_file(source)
+    else:
+        g = parse_string(source)
+    from .parser import apply_setting
+    errs = []
+    for k, v in overrides.items():
+        if v is not None:
+            apply_setting(g.settings, k, str(v), errs, "override")
+    if errs:
+        raise ArchGraphError(errs)
+    layout(g)
+    route(g)
+    if g.settings.routing == "orthogonal" and g.settings.num_spacing_passes() > 0:
+        _engine.expand_congested(g, route, g.settings.num_spacing_passes())
+    g.layout_stats["total_time"] = time.time() - t0
+    return g
+
+
+def to_svg(g: Graph) -> str:
+    from .render.svg import render_svg
+    return render_svg(g)
+
+
+def to_html(g: Graph) -> str:
+    from .render.html import render_html
+    return render_html(g, to_svg(g))
+
+
+def to_json(g: Graph) -> str:
+    from .render.jsonout import render_json
+    return render_json(g)
+
+
+def to_png(g: Graph, path: str, scale: float = 2.0) -> None:
+    from .render.png import render_png
+    render_png(to_svg(g), path, scale)
+
+
+def save(g: Graph, path: str, fmt: Optional[str] = None, scale: float = 2.0) -> str:
+    """Write the diagram; the format follows the extension unless ``fmt`` is given."""
+    fmt = (fmt or os.path.splitext(path)[1].lstrip(".") or "svg").lower()
+    if fmt == "png":
+        to_png(g, path, scale)
+        return path
+    text = {"svg": to_svg, "html": to_html, "htm": to_html, "json": to_json}.get(fmt)
+    if text is None:
+        raise ArchGraphError(f"unsupported output format '{fmt}' (svg, html, json, png)")
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(text(g))
+    return path

archgraph_layout-1.0.0/archgraph/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())