Metadata-Version: 2.5
Name: Graphinate
Version: 0.18.0
Summary: Graphinate. Data to Graphs.
Project-URL: Homepage, https://erivlis.github.io/graphinate
Project-URL: Documentation, https://erivlis.github.io/graphinate
Project-URL: Bug Tracker, https://github.com/erivlis/graphinate/issues
Project-URL: Source, https://github.com/erivlis/graphinate
Author-email: Eran Rivlis <eran@rivlis.info>
License-Expression: LGPL-3.0-or-later
License-File: LICENSE
Keywords: declarative,graph
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx2
Requires-Dist: inflect
Requires-Dist: loguru
Requires-Dist: mappingtools
Requires-Dist: matplotlib
Requires-Dist: networkx
Requires-Dist: networkx-mermaid
Requires-Dist: rich-click
Requires-Dist: strawberry-graphql[asgi,opentelemetry]
Provides-Extra: numpy
Requires-Dist: numpy; extra == 'numpy'
Provides-Extra: perf
Requires-Dist: numpy; extra == 'perf'
Provides-Extra: plot
Requires-Dist: scipy; extra == 'plot'
Provides-Extra: server
Requires-Dist: starlette-prometheus; extra == 'server'
Requires-Dist: uvicorn[standard]; extra == 'server'
Description-Content-Type: text/markdown

# [Graphinate. Data to Graphs.](https://erivlis.github.io/graphinate/)

<img height="360" src="https://github.com/erivlis/graphinate/assets/9897520/dae41f9f-69e5-4eb5-a488-87ce7f51fa32" alt="Graphinate. Data to Graphs.">

<table>
  <tr style="vertical-align: middle;">
    <td>Package</td>
    <td>
      <img alt="PyPI - version" src="https://img.shields.io/pypi/v/graphinate.svg?logo=pypi&logoColor=lightblue">
      <img alt="PyPI - Status" src="https://img.shields.io/pypi/status/graphinate.svg?logo=pypi&logoColor=lightblue">
      <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/graphinate.svg?logo=python&label=Python&logoColor=lightblue">
      <img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dd/graphinate.svg?logo=pypi&logoColor=lightblue">
      <img alt="PyPI - Dependents" src="https://dependents.info/erivlis/graphinate/badge?logo=pypi&logoColor=lightblue">
      <img alt="Libraries.io SourceRank" src="https://img.shields.io/librariesio/sourcerank/pypi/Graphinate.svg?logo=Libraries.io&label=SourceRank">
    </td>
  </tr>
  <tr style="vertical-align: middle;">
    <td>Code</td>
    <td>
      <img alt="GitHub" src="https://img.shields.io/github/license/erivlis/graphinate">
      <img alt="GitHub repo size" src="https://img.shields.io/github/repo-size/erivlis/graphinate.svg?label=Size&logo=git">
      <img alt="GitHub last commit (by committer)" src="https://img.shields.io/github/last-commit/erivlis/graphinate.svg?&logo=git">
      <a href="https://github.com/erivlis/graphinate/graphs/contributors"><img alt="Contributors" src="https://img.shields.io/github/contributors/erivlis/graphinate.svg?&logo=git"></a>
    </td>
  </tr>
  <tr style="vertical-align: middle;">
    <td>Tools</td>
    <td>
      <a href="https://www.jetbrains.com/pycharm/"><img alt="PyCharm" src="https://img.shields.io/badge/PyCharm-FCF84A.svg?logo=PyCharm&logoColor=black&labelColor=21D789&color=FCF84A"></a>
      <a href="https://github.com/astral-sh/uv"><img alt="uv" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" style="max-width:100%;"></a>
      <a href="https://github.com/astral-sh/ruff"><img alt="ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" style="max-width:100%;"></a>
      <a href="https://squidfunk.github.io/mkdocs-material/"><img alt="mkdocs-material" src="https://img.shields.io/badge/Material_for_MkDocs-526CFE?&logo=MaterialForMkDocs&logoColor=white&labelColor=grey"></a>
      <a href="https://github.com/hukkin/mdformat"><img alt="mdformat" src="https://img.shields.io/badge/mdformat-526CFE?&logo=markdown&logoColor=white&labelColor=grey"></a>
      <a href="https://hatch.pypa.io"><img alt="Hatch project" class="off-glb" loading="lazy" src="https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg"></a>
      <a href="https://commitizen-tools.github.io/commitizen"><img alt="commitizen" src="https://custom-icon-badges.demolab.com/badge/commitizen-7e56c2?logo=commitizen&labelColor=grey"></a>
      <a href="https://library-skills.io"><img alt="agentskills" src="https://img.shields.io/badge/agentskills-white?logo=agentskills&labelColor=grey"></a>
    </td>
  </tr>
  <tr style="vertical-align: middle;">
    <td>CI/CD</td>
    <td>
      <a href="https://github.com/erivlis/graphinate/actions/workflows/test.yml"><img alt="Test" src="https://github.com/erivlis/graphinate/actions/workflows/test.yml/badge.svg"></a>
      <a href="https://github.com/erivlis/graphinate/actions/workflows/test-beta.yml"><img alt="Test (Beta)" src="https://github.com/erivlis/graphinate/actions/workflows/test-beta.yml/badge.svg"></a>
      <a href="https://github.com/erivlis/graphinate/actions/workflows/codspeed.yml"><img alt="CodSpeed" src="https://github.com/erivlis/graphinate/actions/workflows/codspeed.yml/badge.svg"></a>
      <a href="https://github.com/erivlis/graphinate/actions/workflows/publish.yml"><img alt="Publish" src="https://github.com/erivlis/graphinate/actions/workflows/publish.yml/badge.svg"></a>
      <a href="https://github.com/erivlis/graphinate/actions/workflows/publish-docs.yaml"><img alt="Publish Docs" src="https://github.com/erivlis/graphinate/actions/workflows/publish-docs.yaml/badge.svg"></a>
    </td>
  </tr>
  <tr style="vertical-align: middle;">
    <td>Scans</td>
    <td>
      <a href="https://codecov.io/gh/erivlis/graphinate"><img alt="Coverage" src="https://codecov.io/gh/erivlis/graphinate/graph/badge.svg?token=POODT8M9NV"/></a>
      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_graphinate"><img alt="Quality Gate Status" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_graphinate&metric=alert_status"></a>
      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_graphinate"><img alt="Security Rating" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_graphinate&metric=security_rating"></a>
      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_graphinate"><img alt="Maintainability Rating" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_graphinate&metric=sqale_rating"></a>
      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_graphinate"><img alt="Reliability Rating" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_graphinate&metric=reliability_rating"></a>
      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_graphinate"><img alt="Lines of Code" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_graphinate&metric=ncloc"></a>
      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_graphinate"><img alt="Vulnerabilities" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_graphinate&metric=vulnerabilities"></a>
      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_graphinate"><img alt="Bugs" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_graphinate&metric=bugs"></a>
      <a href="https://app.codacy.com/gh/erivlis/graphinate/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade"><img alt="Codacy Badge" src="https://app.codacy.com/project/badge/Grade/54b33c3f7313448f9471d01e2a06f037"></a>
      <a href="https://app.codacy.com/gh/erivlis/graphinate/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage"><img alt="Codacy Coverage" src="https://app.codacy.com/project/badge/Coverage/54b33c3f7313448f9471d01e2a06f037"/></a>
      <a href="https://www.codefactor.io/repository/github/erivlis/graphinate"><img src="https://www.codefactor.io/repository/github/erivlis/graphinate/badge" alt="CodeFactor" /></a>
      <a href="https://app.deepsource.com/gh/erivlis/graphinate/" target="_blank"><img alt="DeepSource" title="DeepSource" src="https://app.deepsource.com/gh/erivlis/graphinate.svg/?label=active+issues&show_trend=true&token=5n11jDEmcZB-6eyGR34rQaxF"/></a>
      <a href="https://app.deepsource.com/gh/erivlis/graphinate/" target="_blank"><img alt="DeepSource" title="DeepSource" src="https://app.deepsource.com/gh/erivlis/graphinate.svg/?label=resolved+issues&show_trend=true&token=5n11jDEmcZB-6eyGR34rQaxF"/></a>
      <a href="https://snyk.io/test/github/erivlis/graphinate"><img alt="Snyk" src="https://snyk.io/test/github/erivlis/Graphinate/badge.svg"></a>
      <a href="https://app.codspeed.io/erivlis/graphinate?utm_source=badge"><img src="https://img.shields.io/endpoint?url=https://codspeed.io/badge.json" alt="CodSpeed"/></a>
    </td>
  </tr>
  <tr>
    <td>Mentions</td>
    <td>
      <a href="https://www.youtube.com/live/k01G0b0Y0Jg?si=030OT8sK3BqPyy8r&t=1028"><img alt="PythonBytes Podcast" src="https://img.shields.io/badge/Python_Bytes-Ep. 361-D7F9FF?logo=applepodcasts&labelColor=blue"></a>
      <!-- a href="https://pythonhub.dev/digest/2024-03-10/"><img alt="Static Badge" src="https://img.shields.io/badge/PythonHub-2024.03.10-gold?labelColor=blue"></a -->
      <a href="https://pythonhub.dev/digest/2024-03-10/"><img alt="Python Hub" src="https://custom-icon-badges.demolab.com/badge/Python%20Hub-2024.03.10-gold?logo=pythonhub&labelColor=grey"></a>
    </td>
  </tr>
  <tr>
    <td>Badge</td>
    <td>
       <a href="https://img.shields.io/badge/%F0%9D%94%BE%3D%7B%F0%9D%95%8D%2C%F0%9D%94%BC%7D-Graphinate-darkviolet"><img alt="Graphinate" src="https://img.shields.io/badge/%F0%9D%94%BE%3D%7B%F0%9D%95%8D%2C%F0%9D%94%BC%7D-Graphinate-darkviolet"></a>
    </td>
  </tr>
</table>

## Table of Contents

- [Introduction](#introduction)
    - [Meet Graphinate](#meet-graphinate)
    - [Library at a Glance](#library-at-a-glance)
    - [Links](#links)
- [Quick Start](#quick-start)
    - [Install](#install)
    - [Example](#example)
- [CLI](#cli)
- [Gallery](#gallery)
- [Development](#development)
- [Acknowledgements](#acknowledgements)

## Introduction

### Meet Graphinate

**Graphinate** turns your data into Graphs. Effortlessly.

It is a Python library designed to streamline the pipeline from raw data to structured Graph representations. With Graphinate, you can easily map complex data hierarchies and payloads directly to nodes and edges, creating an efficient retrieval system.

Whether you need to visualize relationships, analyze structure, or serve data via an API, Graphinate provides the tools to bring your graph to life.

**Graphinate** uses and builds upon the excellent [**_NetworkX_**](https://networkx.org/).

### Library at a Glance

#### 📐 The Architect (`graphinate.modeling`)
Define the blueprint of your graph by decorating simple functions (sync or async) that yield your data as nodes and edges, and compose models via `+` or `GraphModel.merge()`.

#### ⚙️ The Engine (`graphinate.engine`)
Traverses models and coordinates lifecycle events (`on_start`, `on_node`, `on_edge`, `on_finish`) across observers via synchronous (`run()`) or asynchronous (`arun()`) execution.

#### 🏗️ The Construction Crew (`graphinate.builders`)
Takes your graph blueprint and constructs various outputs—a queryable `NetworkX` graph, a `D3` dictionary, a `Mermaid` diagram, or an executable `GraphQL` schema (supporting both dynamic and static schema modes).

#### 🎨 The Artists (`graphinate.renderers`)
A suite of tools to visualize your graphs, from `matplotlib` plots to interactive `Mermaid` diagrams.

#### 📡 The Broadcaster (`graphinate.server`)
Instantly serve your graph data as an interactive `GraphQL` API with an embedded, 100% offline 3D WebGL graph viewer requiring zero external CDNs.

#### ⌨️ The Command Center (`graphinate.cli`)
A handy command-line tool to manage and interact with your graph definitions without writing boilerplate code.

### Links

- Website (including documentation): <https://erivlis.github.io/graphinate>
- Source: <https://github.com/erivlis/graphinate>
- Package: <https://pypi.org/project/graphinate>

## Quick Start

### Install

**Graphinate** is available on PyPI:

```shell
pip install graphinate
```

or

```shell
uv add graphinate
```

To install with high-performance vectorized operations (NumPy progressive enhancement):

```shell
pip install "graphinate[perf]"
```

To install with server and offline 3D WebGL viewer support:

```shell
pip install "graphinate[server]"
```

or combine them:

```shell
pip install "graphinate[perf,server]"
```

**Graphinate** officially supports Python >= 3.11.

### Example

```python title="Octagonal Graph"
import graphinate

N: int = 8

# First define a GraphModel instance to hold graph definitions
graph_model: graphinate.GraphModel = graphinate.model(name="Octagonal Graph")


# Register in the Graph Model the edges' supplier generator function
@graph_model.edge()
def edge():
    for i in range(N):
        yield {'source': i, 'target': i + 1}
    yield {'source': N, 'target': 0}


# Use the NetworkX Builder
builder = graphinate.builders.NetworkxBuilder(graph_model)

# Build the NetworkX GraphRepresentation (an nx.Graph instance)
graph = builder.build()

# Display the graph with matplotlib
graphinate.matplotlib.plot(graph, with_edge_labels=True)

# Or create a Mermaid diagram
mermaid_builder = graphinate.builders.MermaidBuilder(graph_model)
diagram: str = mermaid_builder.build()
mermaid_markdown: str = graphinate.mermaid.markdown(diagram)

# Or create a Strawberry GraphQL schema and serve it
gql_builder = graphinate.builders.GraphQLBuilder(graph_model)
schema = gql_builder.build()
graphinate.graphql.server(schema)
```

### Asynchronous Pipelines (`abuild`)

Graphinate natively supports asynchronous generator functions (`async def ... yield`) and coroutines (`async def ... return [...]`):

```python
import asyncio
import graphinate
from graphinate.builders import NetworkxBuilder

m = graphinate.model(name="Async Mesh")

@m.node(type_="service")
async def services():
    yield "auth-service"
    yield "payment-service"

async def main():
    # Asynchronously build across any builder
    nx_graph = await graphinate.abuild(NetworkxBuilder, m)
    print(nx_graph)

asyncio.run(main())
```

## CLI

For detailed information on the command-line interface, please see
the [CLI Usage Guide](https://erivlis.github.io/graphinate/usage/cli/) in the official documentation.

## Gallery

### Python Class AST

#### matplotlib

![graph_ast](https://github.com/erivlis/graphinate/assets/9897520/9e7e1ed2-3a5c-41fe-8c5f-999da4b741ff)

#### 3D Force-Directed Animation

<video width="400"  controls>
  <source src="https://github.com/erivlis/graphinate/assets/9897520/2e9a53b1-5686-4683-a0e4-fbffa850a27b" type="video/mp4">
</video>

### GitHub Repository

![repo_graph](https://github.com/erivlis/graphinate/assets/9897520/9c044bbe-1f21-41b8-b879-95b8362ad48d)

### Web Links

![Web Page Links](https://github.com/erivlis/graphinate/assets/9897520/ea5b00a2-75d1-4d0e-86af-272f20973149)

## Development

For instructions on how to set up your development environment, run tests, and contribute to the project, please see
the [Development Guide](https://erivlis.github.io/graphinate/development/) in the official documentation.

## Acknowledgements

For a list of the dependencies and tools that make Graphinate possible, please see
the [Acknowledgements](https://erivlis.github.io/graphinate/acknowledgements/) page in the official documentation.

______________________________________________________________________

![Alt](https://repobeats.axiom.co/api/embed/683f50f1d2de0e13e468c34a692612c2de4d56bd.svg "Repobeats analytics image")

______________________________________________________________________

<img alt="Work on my Machine" src="https://forthebadge.com/images/badges/works-on-my-machine.svg">

Copyright © 2023-2026 Eran Rivlis
