{"id":24508479,"url":"https://github.com/aplbrain/grand-cypher-io","last_synced_at":"2025-03-15T09:21:00.830Z","repository":{"id":200847521,"uuid":"700959123","full_name":"aplbrain/grand-cypher-io","owner":"aplbrain","description":null,"archived":false,"fork":false,"pushed_at":"2023-10-23T19:38:13.000Z","size":35,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-01-22T00:16:17.782Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aplbrain.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-10-05T16:18:10.000Z","updated_at":"2024-02-22T16:28:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"b11506ad-7a91-4935-8883-3a2a25112966","html_url":"https://github.com/aplbrain/grand-cypher-io","commit_stats":null,"previous_names":["aplbrain/grand-cypher-io"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aplbrain%2Fgrand-cypher-io","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aplbrain%2Fgrand-cypher-io/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aplbrain%2Fgrand-cypher-io/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aplbrain%2Fgrand-cypher-io/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aplbrain","download_url":"https://codeload.github.com/aplbrain/grand-cypher-io/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243707942,"owners_count":20334733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-22T00:16:31.416Z","updated_at":"2025-03-15T09:21:00.808Z","avatar_url":"https://github.com/aplbrain.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=center\u003egrand-cypher-io\u003c/h1\u003e\n\u003cp align=center\u003eFile IO routines for reading and writing OpenCypher files\u003c/p\u003e\n\u003cp align=center\u003e\u003ca href=\"https://pypi.org/project/grand-cypher-io/\"\u003e\u003cimg alt=\"PyPI - Version\" src=\"https://img.shields.io/pypi/v/grand-cypher-io?style=for-the-badge\u0026logo=pypi\"\u003e\u003c/a\u003e\u003c/p\u003e\n\u003chr /\u003e\n\n\n```\npip install grand-cypher-io\n```\n\n## Why?\n\n-   To enable the use of OpenCypher files as a standard graph interchange format.\n-   To simplify reading and writing in-memory Python graphs to a Neo4j or Neptune database.\n-   To serialize and deserialize graphs for long-term (e.g., archival) immutable storage.\n\n## Compatibilities\n\n-   All routines that expect a graph can be run with [Grand](https://github.com/aplbrain/grand) `Graph.nx` objects.\n-   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.\n-   Designed for use with [AWS Neptune](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load-tutorial-format-opencypher.html)\n\n## Usage\n\n### Export a graph to OpenCypher-readable files\n\n```python\nfrom grand_cypher_io import graph_to_opencypher_buffers\n# `graph` is nx.DiGraph or compatible\nvert_buffer, edge_buffer = graph_to_opencypher_buffers(graph)\nwith open('vertices.csv', 'w') as f:\n    f.write(vert_buffer.read())\nwith open('edges.csv', 'w') as f:\n    f.write(edge_buffer.read())\n```\n\n### Import a graph from OpenCypher-readable files\n\n```python\nfrom grand_cypher_io import opencypher_buffers_to_graph\nwith open('vertices.csv', 'r') as f:\n    vert_buffer = io.StringIO(f.read())\nwith open('edges.csv', 'r') as f:\n    edge_buffer = io.StringIO(f.read())\ngraph = opencypher_buffers_to_graph(vert_buffer, edge_buffer)\n```\n\n## Usage Considerations\n\n### Edge addition implies vertices\n\nWhen 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.\n\nBecause these implicit vertices have no properties, they are easy to detect and filter out of the graph after importing, if desired.\n\nThis behavior also means that it is possible to create a full structural graph from a set of edges alone, without any vertices.\n\n### The `__labels__` magic attribute\n\nFollowing the [Grand-Cypher](https://github.com/aplbrain/grand-cypher) convention, the `__labels__` attribute is used to store the labels of a node. This is 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.\n\nLikewise, the `__labels__` attribute is used to populate the `labels` attribute of a node when reading from an OpenCypher file.\n\n\u003cp align='center'\u003e\u003csmall\u003eMade with 💙 at \u003ca href='http://www.jhuapl.edu/'\u003e\u003cimg alt='JHU APL' align='center' src='https://user-images.githubusercontent.com/693511/62956859-a967ca00-bdc1-11e9-998e-3888e8a24e86.png' height='42px'\u003e\u003c/a\u003e\u003c/small\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faplbrain%2Fgrand-cypher-io","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faplbrain%2Fgrand-cypher-io","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faplbrain%2Fgrand-cypher-io/lists"}