Metadata-Version: 2.4
Name: grand-cypher-io
Version: 0.2.0
Summary: File IO routines for reading and writing OpenCypher files
Project-URL: Homepage, https://github.com/aplbrain/grand-cypher-io
Project-URL: Issues, https://github.com/aplbrain/grand-cypher-io/issues
Project-URL: Source, https://github.com/aplbrain/grand-cypher-io
Project-URL: Changelog, https://github.com/aplbrain/grand-cypher-io/blob/main/CHANGELOG.md
Author-email: Jordan Matelsky <opensource@matelsky.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.11
Requires-Dist: networkx<4,>=3.4
Requires-Dist: tqdm<5,>=4.67
Description-Content-Type: text/markdown

<h1 align=center>grand-cypher-io</h1>
<p align=center>File IO routines for reading and writing OpenCypher files</p>
<p align=center><a href="https://pypi.org/project/grand-cypher-io/"><img alt="PyPI - Version" src="https://img.shields.io/pypi/v/grand-cypher-io?style=for-the-badge&logo=pypi"></a></p>
<hr />


```
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](https://github.com/aplbrain/grand) `Graph.nx` objects.
-   You can mock most of a Neo4j database, using this repository for IO and in conjunction with [Grand-Cypher](https://github.com/aplbrain/grand-cypher) for query execution.
-   Designed for use with [AWS Neptune](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load-tutorial-format-opencypher.html)

## Usage

### Export a graph to OpenCypher-readable files

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

```python
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](https://docs.astral.sh/uv/) for environments, dependency
locking, and builds:

```shell
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](https://github.com/aplbrain/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](https://github.com/aplbrain/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.

<p align='center'><small>Made with 💙 at <a href='http://www.jhuapl.edu/'><img alt='JHU APL' align='center' src='https://user-images.githubusercontent.com/693511/62956859-a967ca00-bdc1-11e9-998e-3888e8a24e86.png' height='42px'></a></small></p>
