What Input Formats Does graphviz2drawio Accept? File, String, and AGraph Support Explained

The graphviz2drawio.convert() function accepts pygraphviz.AGraph objects, file path strings, pathlib.Path objects, file-like handles, and raw DOT source strings, normalizing them internally through the _load_pygraphviz_agraph helper.

The graphviz2drawio library provides a bridge between Graphviz diagrams and draw.io XML, but understanding what input formats are supported is critical for integration. This article examines the convert() implementation in hbmartin/graphviz2drawio to detail exactly how the library handles files, strings, and native graph objects.

Accepted graphviz2drawio Input Types

The convert() function signature in graphviz2drawio/graphviz2drawio.py (lines 13‑16) declares the graph_to_convert parameter as a union type:

def convert(
    graph_to_convert: AGraph | str | TextIOBase | Path | TextIO,
    layout_prog: str = "dot",
) -> str:

The private helper _load_pygraphviz_agraph (lines 55‑77) normalizes these inputs before processing. Here is how each type is handled:

PyGraphviz AGraph Objects

Passing an instantiated pygraphviz.AGraph object returns it unchanged. This allows callers who have already built or manipulated a graph programmatically to convert it directly without serialization overhead.

from pygraphviz import AGraph
from graphviz2drawio import graphviz2drawio

g = AGraph(string="digraph { X -> Y }")
xml = graphviz2drawio.convert(g)

File Paths and Pathlib Objects

Strings ending with .dot, .gv, or .txt are treated as filenames and opened via AGraph(filename=…). Additionally, pathlib.Path objects are passed directly to PyGraphviz for filesystem resolution.

from pathlib import Path
from graphviz2drawio import graphviz2drawio

# String path

xml = graphviz2drawio.convert("network.gv")

# Path object

xml = graphviz2drawio.convert(Path("graphs/diagram.dot"))

DOT Source Strings

Raw Graphviz source strings are accepted if they end with } or match a digraph/graph header pattern. Lines 60‑71 of the source use a regular expression to detect valid DOT syntax and force parsing via AGraph(string=…), avoiding a known PyGraphviz bug where leading comments could be misinterpreted as filenames.

dot_src = """digraph {
    A -> B [label="edge"]
    B -> C
}"""
xml = graphviz2drawio.convert(dot_src)

File-like Objects and Streams

Any object with a callable read() method (including io.StringIO, sys.stdin, or TextIOBase subclasses) is consumed as text and passed to AGraph(string=…). This enables piping workflows and in-memory processing.

import sys
from graphviz2drawio import graphviz2drawio

# From stdin

xml = graphviz2drawio.convert(sys.stdin)

# From StringIO

import io
buffer = io.StringIO("digraph { a -> b }")
xml = graphviz2drawio.convert(buffer)

Input Normalization Logic

The _load_pygraphviz_agraph function implements the decision tree for format detection:

• Lines 55‑56: Checks for existing AGraph instances via isinstance.
• Lines 57‑72: Inspects strings for file extensions or DOT headers. If the string ends with .dot, .gv, or .txt, it is opened as a file; otherwise, it is parsed as source code.
• Lines 74‑76: Tests for the presence of a read attribute to identify file-like objects.

If the input cannot be resolved to a valid Graphviz representation, PyGraphviz raises an exception that propagates to the caller, typically resulting in an UnableToParseGraphError defined in graphviz2drawio/models/Errors.py.

Complete Code Examples

Convert a Local DOT File

from graphviz2drawio import graphviz2drawio

xml_output = graphviz2drawio.convert("examples/hello.gv")
print(xml_output)

Convert Using Standard Input

Useful for shell pipelines:

cat mygraph.dot | python -m graphviz2drawio --stdout

Or programmatically:

import sys
from graphviz2drawio import graphviz2drawio

xml = graphviz2drawio.convert(sys.stdin)

Convert a Pre-built AGraph with Custom Layout

from pygraphviz import AGraph
from graphviz2drawio import graphviz2drawio

g = AGraph()
g.add_edge("Start", "End")
xml = graphviz2drawio.convert(g, layout_prog="neato")

Summary

• graphviz2drawio accepts six input categories: pygraphviz.AGraph objects, file path strings, pathlib.Path objects, DOT source strings, and file-like objects (TextIOBase).
• Input detection occurs in _load_pygraphviz_agraph within graphviz2drawio/graphviz2drawio.py, which uses extension checks and regex pattern matching to distinguish files from raw DOT code.
• The CLI entry point in graphviz2drawio/__main__.py forwards arguments to the same convert() function, ensuring consistent behavior between library and command-line usage.

Frequently Asked Questions

Can I pass a file object opened in binary mode to graphviz2drawio?

No. The library expects text-based streams that comply with TextIOBase or provide a read() method returning strings. Binary file objects will raise a TypeError during the normalization phase when the content is passed to AGraph(string=…).

How does graphviz2drawio distinguish between a filename and a DOT string?

The _load_pygraphviz_agraph function checks if the string ends with .dot, .gv, or .txt. If not, it applies a regex to detect Graphviz headers (digraph or graph). If the string matches DOT syntax, it is parsed directly; otherwise, it is treated as a file path and passed to AGraph(filename=…).

What happens if the input file does not exist?

If a string argument does not match DOT syntax patterns and refers to a non-existent path, PyGraphviz will raise a file-not-found error during the AGraph(filename=…) call. This error propagates uncaught through convert(), allowing standard Python exception handling to manage missing resources.

Is there a performance difference between passing an AGraph object versus a string?

Yes. Passing an AGraph object avoids the parsing overhead required to convert a DOT string or read a file from disk. For high-throughput applications where the same graph is converted multiple times with different layout programs, instantiate AGraph once and reuse the object.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}