feat: export() writes DOT, Mermaid, GraphML, ELK JSON or a rendered image

[petercorke]

Summary

One method, g.export(filename=None, format=None, **options), writes the graph as DOT, Mermaid, GraphML, ELK JSON, or a rendered image.

g.export("graph.graphml")                    # format inferred from the extension
text = g.export(format="mermaid", direction="LR", fence=True)
g.export("graph.svg")                        # rendered with GraphViz

format	Extensions	Positions	Options	Needs
dot	.dot .gv	pos="x,y!"	direction, colorcomponents, costs	nothing
mermaid	.mmd .mermaid	no (not expressible)	direction, colorcomponents, costs, fence	nothing
graphml	.graphml	x, y, coord	none	nothing
elk	.elk.json .elk	x, y	size, layout_options	nothing
svg pdf png jpg gif ps	same	via neato	engine, direction, colorcomponents, costs	GraphViz executables

• No new dependency. The text formats use only the standard library; the image formats run dot/neato directly and raise a clear RuntimeError if it is missing. (An earlier attempt imported the graphviz Python package at module top level, even for the text formats.)
• Exporters are plain functions in pgraph.exporters, registered with @register_exporter(name, *extensions), so a format can be added without touching PGraph.py.
• dotfile() and showgraph() are kept as thin wrappers, so this is additive.

Fixes over the old dotfile()

• Reproducible output. It iterated graph.edges(), a set, so the order changed between runs. Edges are now written in the order of their vertices, and parallel edges and self-loops are all kept.
• Escaping. Names containing ", \, a newline, <, & are escaped for each format; Mermaid, GraphML and ELK use generated ids so any name is valid.
• Edge cost is carried (DOT/Mermaid label, GraphML cost, ELK properties.cost); dotfile() leaves it unlabelled as before.
• showgraph() no longer uses shell=True, and reports a missing GraphViz instead of silently doing nothing.
• A path is closed even if writing fails; a file object is never closed.

For review

• export() returns the text when no filename is given and returns None when it writes, whereas dotfile() prints. Easy to change; I preferred composability.
• showgraph(display=False) returns the PDF path (useful for tests and notebooks).
• Mermaid cannot express positions, so coordinates are dropped there; this is documented.

Tests

tests/test_export.py, 50 tests: golden strings for dot and mermaid, parse-back for GraphML (ElementTree) and ELK (json), the multigraph and self-loop cases, escaping, reproducibility, dispatch and errors, a user-registered exporter, and real GraphViz rendering (skipped when dot is absent; the missing-program error path is tested without it). Full suite 213 passing, mypy and pyflakes clean on the changed files.

Recovered from an earlier uncommitted attempt (2026-09-02), then ported to the current code and redesigned; see claude-notes/export-formats-design.md locally.

🤖 Generated with Claude Code

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 175 complexity · 0 duplication

Metric	Results
Complexity	175
Duplication	0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[codecov]

Codecov Report

❌ Patch coverage is 99.58848% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 93.27%. Comparing base (7c68cab) to head (099c699).

Files with missing lines	Patch %	Lines
src/pgraph/exporters.py	99.47%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #34      +/-   ##
==========================================
+ Coverage   90.76%   93.27%   +2.50%     
==========================================
  Files           2        3       +1     
  Lines         845     1055     +210     
==========================================
+ Hits          767      984     +217     
+ Misses         78       71       -7     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.