Metadata-Version: 2.4
Name: graphitedb
Version: 0.5
Summary: A clean, embedded graph database engine for Python.
Author-email: Mahan Khalili <khalili1388mahan@gmail.com>
Maintainer-email: Mahan Khalili <khalili1388mahan@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Mahan Khalili
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://mkh-user.graphite.io/graphite
Project-URL: Source, https://github.com/mkh-user/graphite
Project-URL: Download, https://pypi.org/project/graphitedb/
Project-URL: Changelog, https://github.com/mkh-user/graphite/blob/main/CHANGELOG.md
Project-URL: Releasenotes, https://github.com/mkh-user/graphite/releases
Project-URL: Documentation, https://mkh-user.graphite.io/graphite
Project-URL: Issues, https://github.com/mkh-user/graphite/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Database :: Database Engines/Servers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typing_extensions~=4.15.0
Provides-Extra: dev
Requires-Dist: pytest~=9.0.2; extra == "dev"
Requires-Dist: pylint~=4.0.4; extra == "dev"
Requires-Dist: ty~=0.0.46; extra == "dev"
Provides-Extra: benchmark
Requires-Dist: pympler~=1.1; extra == "benchmark"
Requires-Dist: typer~=0.24.1; extra == "benchmark"
Requires-Dist: tqdm~=4.67.1; extra == "benchmark"
Dynamic: license-file

# Graphite

A clean, embedded graph database engine for Python.

---

**Graphite** is a lightweight yet flexible **graph database engine** implemented in pure Python.
It is designed to model graph-like data inside large Python codebases **without introducing the complexity of an external database**.

Optimized for graphs up to 500K nodes (tested up to 1M). 10x faster than NetworkX, with pure Python simplicity.
(Repeat benchmark available at `tests/benchmark.py`)

---

## Features

### 🧩 Embedded by Design
Graphite is not a separate service or infrastructure dependency.
It lives inside your project, evolves with it, and collaborates naturally with your existing code.

No servers. No ports. No deployment headaches.

---

### 🛠 Ready-made, Customizable Module
Graphite is intentionally simple and hackable.
You can fork it, modify it, or deeply integrate it into your project without fighting rigid abstractions.

The database adapts to your project — not the other way around.

---

### 🐍 Native Python API
Everything is done through Python APIs.
No query strings.
DSL parsing is just an optional layer.
No context switching.

Your editor already knows how to autocomplete and document your queries.

---

### 🔍 Query? It’s Code.
Queries are built by chaining Python functions on the `QueryResult` object.

- Zero parsing cost
- Full IDE support
- Refactor-safe
- Debuggable

---

### 🔄 Runtime Evolution
Change structures, data, or even engine behavior **at runtime**.
No shutdowns.
No migrations.
No waiting.

---

### 🧱 Structure-Oriented Modeling
Define:
- node types
- relation types
- fields
- base types
- valid forms

Model your domain explicitly and safely.

---

### 🧬 Node Inheritance
Create base node types and extend them with shared properties and advanced relationships.

---

### ✨ Simple, Predictable Syntax
From defining structures to querying data, every step favors clarity and minimal syntax.

---

### 💾 Serializable
Persist the entire database into a single file.

---

## Installation

Install from **PyPI**:

```bash
pip install graphitedb
```

---

## Why Graphite?

Graphite was extracted from a **large production codebase** where Neo4j introduced more complexity than value.

Neo4j is a powerful tool — but in large projects, adding a separate graph database often increases:

* infrastructure complexity
* deployment cost
* maintenance burden
* cognitive load on developers

Graphite exists for cases where this cost is **not justified**.

It provides graph modeling **without adding another system to operate**.

### Comparation

| Feature                 | Neo4j                               | Graphite                                  | Custom Graph Engine                     |
|-------------------------|-------------------------------------|-------------------------------------------|-----------------------------------------|
| **Bug Safety**          | **🥇Very High:**<br>Mature & tested | **🥈High:**<br>Unit tests, monitored      | **🥉Low-Medium:**<br>You manage testing |
| **Implementation**      | **🥈High:**<br>Setup & Cypher       | **🥇Low:**<br>Embed easily                | **🥉Very High:**<br>Build from scratch  |
| **Flexibility**         | **🥈High:**<br>Complex queries      | **🥉Medium:**<br>Limited but extendable   | **🥇Very High:**<br>Fully customizable  |
| **Performance**         | **🥇High:**<br>Optimized large data | **🥈Medium:**<br>Good for small/medium    | **❓Unknown:**<br>Depends on design      |
| **Scalability**         | **🥇High:**<br>Cluster & sharding   | **🥈Medium:**<br>Single-node & Base types | **❓Unknown:**<br>Possible but hard      |
| **Support / Community** | **🥇Very High:**<br>Large & active  | **🥈Medium:**<br>Docstrings only          | **🥉Low:**<br>Internal only             |
| **Customizability**     | **🥉Low:**<br>Limited to API        | **🥈High:**<br>Open source                | **🥇Very High:**<br>Full control        |
| **Ease of Use**         | **🥈Medium:**<br>Learn Cypher       | **🥇High:**<br>Quick & simple             | **🥉Low:**<br>Needs study & test        |

---

## Example Usage

```python
import graphite

def example_complete_dsl_loading():
    engine = graphite.engine()

    complete_dsl = """
    # Define node types
    node Person
        name: string
        age: int

    node User from Person
        id: string
        email: string

    node Object
    node Book from Object
        title: string
        n_pages: int

    node Car from Object
        model: string
        year: int

    # Define relation types
    relation FRIEND both
        Person - Person
        since: date

    relation OWNER reverse OWNED_BY
        Person -> Object
        since: date
        purchased_at: date

    relation AUTHOR reverse AUTHORED_BY
        Person -> Book
        year: int

    # Create nodes
    User, user_1, "Joe Doe", 32, "joe4030", "joe@email.com"
    User, user_2, "Jane Smith", 28, "jane28", "jane@email.com"
    User, user_3, "Bob Wilson", 45, "bob45", "bob@email.com"
    User, user_4, "Alice Brown", 22, "alice22", "alice@email.com"

    Book, book_1, "The Great Gatsby", 180
    Book, book_2, "Python Programming", 450
    Book, book_3, "Graph Databases", 320

    Car, car_1, "Toyota Camry", 2020
    Car, car_2, "Honda Civic", 2018

    # Create relations
    user_1 -[FRIEND, 2020-05-15]- user_2
    user_1 -[FRIEND, 2019-08-22]- user_3
    user_2 -[FRIEND, 2021-01-10]- user_4

    user_1 -[OWNER, 2021-03-01, 2021-02-15]-> car_1
    user_2 -[OWNER, 2019-06-20, 2019-05-10]-> book_1
    user_3 -[OWNER, 2022-11-05, 2022-10-20]-> book_2

    user_1 -[AUTHOR, 2020]-> book_3
    user_2 -[AUTHOR, 2021]-> book_2
    """

    engine.parse(complete_dsl)

    users = engine.query.User.get()
    print([u["name"] for u in users])

    return engine
```

More examples are available in `examples/` in the GitHub repository.

See `docs/` for documentation and API reference.

---

_MIT 2026 Mahan Khalili_
