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

> Learn what input formats graphviz2drawio accepts. Discover support for AGraph, file paths, strings, and more for seamless diagram generation from graphviz.

- Repository: [Harold Martin/graphviz2drawio](https://github.com/hbmartin/graphviz2drawio)
- Tags: api-reference
- Published: 2026-03-03

---

**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`](https://github.com/hbmartin/graphviz2drawio/blob/main/graphviz2drawio/graphviz2drawio.py) (lines 13‑16) declares the `graph_to_convert` parameter as a union type:

```python
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.

```python
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.

```python
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.

```python
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.

```python
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`](https://github.com/hbmartin/graphviz2drawio/blob/main/graphviz2drawio/models/Errors.py).

## Complete Code Examples

### Convert a Local DOT File

```python
from graphviz2drawio import graphviz2drawio

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

```

### Convert Using Standard Input

Useful for shell pipelines:

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

```

Or programmatically:

```python
import sys
from graphviz2drawio import graphviz2drawio

xml = graphviz2drawio.convert(sys.stdin)

```

### Convert a Pre-built AGraph with Custom Layout

```python
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`](https://github.com/hbmartin/graphviz2drawio/blob/main/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`](https://github.com/hbmartin/graphviz2drawio/blob/main/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.