grand-cypher-io

File IO routines for reading and writing OpenCypher files

pip install grand-cypher-io

Why?

• To enable the use of OpenCypher files as a standard graph interchange format.
• To simplify reading and writing in-memory Python graphs to a Neo4j or Neptune database.
• To serialize and deserialize graphs for long-term (e.g., archival) immutable storage.

Compatibilities

• All routines that expect a graph can be run with Grand Graph.nx objects.
• You can mock most of a Neo4j database, using this repository for IO and in conjunction with Grand-Cypher for query execution.
• Designed for use with AWS Neptune

Usage

Export a graph to OpenCypher-readable files

import networkx as nx

from grand_cypher_io import graph_to_opencypher_buffers

# `graph` is an nx.Graph or compatible object.
vert_buffer, edge_buffer = graph_to_opencypher_buffers(graph)
with open("vertices.csv", "w") as f:
    f.write(vert_buffer.read())
with open("edges.csv", "w") as f:
    f.write(edge_buffer.read())

Import a graph from OpenCypher-readable files

from grand_cypher_io import opencypher_buffers_to_graph

graph = opencypher_buffers_to_graph("vertices.csv", "edges.csv")

Python 3.11 through 3.13 are supported.

Imports create an nx.MultiDiGraph by default so parallel OpenCypher relationships are preserved. Pass to_graph= to populate another NetworkX graph type; importing parallel relationships into a simple graph raises an error rather than discarding data.

Development

The project uses uv for environments, dependency locking, and builds:

uv sync --locked --all-groups
uv run ruff check .
uv run ruff format --check .
uv run pytest
uv build

Usage Considerations

Edge addition implies vertices

When adding an edge to a graph, the vertices of the edge are also added to the graph. This is counter to the behavior of Neo4j imports, but compatible with the Grand graph library assumptions, and greatly reduces the inner-loop complexity of the import process.

Because these implicit vertices have no properties, they are easy to detect and filter out of the graph after importing, if desired.

This behavior also means that it is possible to create a full structural graph from a set of edges alone, without any vertices.

The __labels__ magic attribute

Following the Grand-Cypher convention, the __labels__ attribute is used to store the labels of a node. Writers accept either one string or an iterable of strings. The __labels__ attribute is not required, but if it is present, it will be used to populate the labels attribute of the node for the purposes of writing to an OpenCypher file.

Readers always store __labels__ as a set of strings. Typed OpenCypher properties are converted to their corresponding Python scalar types.

Made with 💙 at