networkx-graphql

The QL in the nx.Graph

---

Package
Code
Tools
CI/CD
Scans

Overview

networkx-graphql brings GraphQL querying to NetworkX graph structures in Python. By leveraging Strawberry GraphQL and Graphinate, it automatically generates strongly-typed GraphQL schemas directly from NetworkX graph instances and serves them via an interactive GraphQL web interface.

Whether you are working with simple undirected graphs, complex directed networks, or multi-edge graphs, networkx-graphql allows you to explore and query node relationships with zero GraphQL boilerplate.

---

Features

• ⚡ Instant Schema Generation: Automatically derive Strawberry GraphQL schemas from NetworkX graphs in a single line of code.
• 🕸️ Full NetworkX Compatibility: Seamlessly supports nx.Graph, nx.DiGraph, nx.MultiGraph, and nx.MultiDiGraph.
• 🏷️ Custom Node Classification: Supply custom extractor functions to dynamically extract node types and structure GraphQL schemas accordingly.
• 🌐 Embedded GraphQL Server: Built-in HTTP server with an interactive GraphiQL playground powered by Uvicorn and Starlette.
• 🐍 Fully Typed: Written with Python 3.11+ type annotations for maximum IDE support and type safety.

---

Installation

Install networkx-graphql using pip:

pip install networkx-graphql

Or using uv:

uv add networkx-graphql

Server Extra

To include web server dependencies (uvicorn, starlette-prometheus), install with the server extra:

pip install "networkx-graphql[server]"
# or with uv
uv add "networkx-graphql[server]"

---

Quickstart

Spin up a GraphQL server for a NetworkX graph in 3 lines:

import networkx as nx
import networkx_graphql as nxg

# 1. Create any NetworkX graph
graph = nx.ladder_graph(5)

# 2. Generate the GraphQL schema
schema = nxg.schema(graph)

# 3. Start the GraphQL server (default port: 8073)
nxg.run(schema, port=8073)

Now navigate in your browser to http://localhost:8073 (which will redirect to `http://localhost:8073/viewer’), to view the graph using 3D force-directed graph visualizer for the underlying NetworkX graph. The viewer is powered by Graphinate.

Explore the GraphQL schema and run queries using the built-in GraphiQL interface at http://localhost:8073/graphiql.

---

Usage Examples

Custom Node Type Extractor

By default, all nodes are categorized under a generic type ('node'). You can provide a custom node_type_extractor function to map graph nodes to distinct GraphQL types:

import networkx as nx
import networkx_graphql as nxg

# Create a graph with different node types
graph = nx.DiGraph(name="CompanyNetwork")
graph.add_node("alice", role="manager")
graph.add_node("bob", role="developer")
graph.add_edge("alice", "bob", relationship="manages")


# Define a custom node type extractor
def extract_node_type(node: str) -> str:
    role = graph.nodes[node].get("role", "employee")
    return role.capitalize()


# Generate schema with custom node types
schema = nxg.schema(graph, node_type_extractor=extract_node_type)

# Serve the GraphQL schema
nxg.run(schema, port=8073)

---

API Reference

networkx_graphql.schema(graph, node_type_extractor=None)

Generates a strawberry.Schema from a NetworkX graph instance.

Parameter	Type	Description	Default
graph	nx.Graph	Any NetworkX graph instance (Graph, DiGraph, MultiGraph, MultiDiGraph).	Required
node_type_extractor	Extractor \| None	A function or callable (node) -> str that returns a GraphQL type name for a node.	None

Returns: strawberry.Schema - The generated Strawberry GraphQL schema object.

---

networkx_graphql.run(graphql_schema, port=8073)

Launches an HTTP server to serve the Strawberry GraphQL schema.

Parameter	Type	Description	Default
graphql_schema	strawberry.Schema	The Strawberry GraphQL schema to serve.	Required
port	int	The HTTP port to run the server on.	8073

---

Development & Testing

This project uses uv for dependency management and pytest for testing.

Setup Development Environment

# Clone the repository
git clone https://github.com/erivlis/networkx-graphql.git
cd networkx-graphql

# Install dependencies with uv
uv sync --all-extras

Running Tests & Linting

# Run pytest test suite
uv run pytest

# Run linter checks
uv run ruff check .

Running Benchmarks

Performance is tracked continuously with CodSpeed. The benchmarks live in benchmarks/ and are regular pytest tests using the benchmark fixture provided by pytest-codspeed.

# Run the benchmarks locally (walltime measurements, no instrumentation)
uv run pytest benchmarks --codspeed

# Run them the way CI does, with CPU simulation via the CodSpeed CLI
codspeed run --mode simulation -- uv run pytest benchmarks --codspeed

---

License

Distributed under the terms of the GNU Lesser General Public License v3.0 or later (LGPLv3+).

This site is open source. Improve this page.