post-graph 0.1.0__tar.gz

post_graph-0.1.0/.gitignore

@@ -0,0 +1,222 @@
+# Secrets and keys
+**/*secret*
+**/*key*
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

post_graph-0.1.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: post-graph
+Version: 0.1.0
+Summary: High-performance PostgreSQL-backed graph database library supporting multi-tenant realms, schema-per-realm, shadow auditing, and append-only data history.
+Project-URL: Homepage, https://github.com/crajah/post-graph
+Project-URL: Repository, https://github.com/crajah/post-graph
+Author-email: Chandan Rajah <chandan.rajah@gmail.com>
+License: MIT
+Keywords: asyncpg,database,graph,postgres,postgresql,sqlalchemy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Requires-Python: >=3.9
+Requires-Dist: asyncpg>=0.29.0
+Provides-Extra: all
+Requires-Dist: sqlalchemy>=2.0.0; extra == 'all'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2.0.0; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+# post-graph: Generic PostgreSQL Graph Database Library
+
+A generic, high-performance mechanism to use PostgreSQL as a graph database in Python. It supports **multi-tenancy (realms)**, automatic **shadow audit tables**, and advanced **graph traversals (recursive CTEs)**.
+
+Features:
+*   **Table-Per-Vertex & Table-Per-Edge Architecture**: Graph elements are mapped to individual tables, utilizing PostgreSQL's native schema constraints and relations.
+*   **Multi-Tenancy**: Built-in logical isolation using a `realm` field, allowing multiple tenants to share the same database while enforcing partition boundaries.
+*   **Shadow Auditing**: Automatically creates a matching `{table_name}_audit` table for every vertex and edge table. Operates at the database trigger level to log operations (`INSERT`, `UPDATE`, `DELETE`), capturing the complete row history and the initiating `user_id` passed securely via session parameters.
+*   **Dynamic Metadata Discovery**: Queries the PostgreSQL catalog tables to dynamically determine the structure and connections of edge tables during traversals.
+*   **Advanced Graph CTEs**: High-performance recursive CTE queries for single-hop neighbor queries, multi-hop path traversals, and shortest-path calculation (with early-termination and cycle prevention).
+*   **Multiple Backend Drivers**: Includes native clients for raw `asyncpg` and `SQLAlchemy` (v2.0 async connections).
+
+---
+
+## Architecture Schema
+
+The schema design isolates graphs by tenant `realm`, ensuring that edges can only link vertices belonging to the exact same realm.
+
+```mermaid
+erDiagram
+    users {
+        text realm PK
+        bigserial id PK
+        text fqid
+        jsonb payload
+        timestamptz created_at
+        timestamptz updated_at
+    }
+    posts {
+        text realm PK
+        bigserial id PK
+        text fqid
+        jsonb payload
+        timestamptz created_at
+        timestamptz updated_at
+    }
+    likes {
+        text realm PK, FK
+        bigserial id PK
+        text fqid
+        bigint from_id FK
+        bigint to_id FK
+        text relation_type
+        jsonb payload
+        timestamptz created_at
+        timestamptz updated_at
+    }
+    users_audit {
+        bigint audit_id PK
+        text realm
+        text action
+        text changed_by
+        timestamptz changed_at
+        jsonb old_row
+        jsonb new_row
+    }
+    users_data {
+        bigserial data_id PK
+        text realm FK
+        bigint id FK
+        jsonb payload
+        timestamptz timestamp
+    }
+
+    users ||--o{ likes : "from_id"
+    posts ||--o{ likes : "to_id"
+    users ||--o{ users_audit : "logs changes"
+    users ||--o{ users_data : "appends records"
+```
+
+---
+
+## Installation
+
+Define dependencies in your environment:
+```bash
+pip install -r requirements.txt
+```
+
+---
+
+## Quick Start
+
+### 1. Raw `asyncpg` Client (`AsyncPostGraph`)
+
+```python
+import asyncio
+from post_graph import AsyncPostGraph
+
+async def main():
+    # Connect to PostgreSQL
+    client = AsyncPostGraph(dsn="postgresql://postgres:postgres@localhost:5432/postgres")
+    await client.connect()
+
+    # Create schema (with optional edge-to-vertex cascade deletion parameters)
+    await client.create_vertex_table("users")
+    await client.create_vertex_table("posts")
+    await client.create_edge_table(
+        "likes", 
+        from_vertex_table="users", 
+        to_vertex_table="posts",
+        cascade_delete_from=False, # If True, deleting an edge deletes the source vertex
+        cascade_delete_to=False    # If True, deleting an edge deletes the target vertex
+    )
+
+    # Add vertices (isolated in realm 'tenant_1' and audited as user 'admin_alice')
+    await client.add_vertex(
+        table_name="users", 
+        realm="tenant_1", 
+        vertex_id="u_1", 
+        payload={"username": "alice"}, 
+        user_id="admin_alice"
+    )
+    await client.add_vertex(
+        table_name="posts", 
+        realm="tenant_1", 
+        vertex_id="p_1", 
+        payload={"title": "Hello World"}, 
+        user_id="admin_alice"
+    )
+
+    # Link vertices with an edge (with optional cycle prevention checks)
+    await client.add_edge(
+        table_name="likes",
+        realm="tenant_1",
+        edge_id="e_1",
+        from_id="u_1",
+        to_id="p_1",
+        relation_type="like",
+        payload={"reaction": "heart"},
+        user_id="user_bob",
+        check_cycle=True # Optional: raise CyclicReferenceError if a loop would be created
+    )
+
+    # Query neighbors
+    neighbors = await client.get_neighbors(
+        realm="tenant_1", 
+        vertex_table="users", 
+        vertex_id="u_1", 
+        edge_tables=["likes"]
+    )
+    for vertex, edge in neighbors:
+        print(f"Connected to post: {vertex.id} with payload: {vertex.payload}")
+
+    # Delete an entire realm (tenant) from all tables (including audits)
+    deleted_rows = await client.delete_realm("tenant_1")
+    print(f"Cleared {deleted_rows} rows belonging to tenant_1")
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+### 2. SQLAlchemy Client (`SQLAlchemyPostGraph`)
+
+Integrates with your existing SQLAlchemy async architecture:
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+from post_graph import SQLAlchemyPostGraph
+
+engine = create_async_engine("postgresql+asyncpg://postgres:postgres@localhost:5432/postgres")
+client = SQLAlchemyPostGraph(engine)
+
+# All schema creation and graph operation interfaces match the AsyncPostGraph client
+await client.create_vertex_table("users")
+```
+
+## Advanced Graph Operations
+
+### Direct Object-Level Traversal
+If a `Vertex` is loaded from a client, you can traverse directly from the object using standard OOP calling patterns. 
+
+*Note: Since `from` is a reserved keyword in Python, the reverse traversal method is named `.from_()` (with an underscore).*
+
+```python
+# Load a vertex
+alice_v = await client.get_vertex(table_name="users", realm="tenant_1", vertex_id="u_1")
+
+# 1. Forward traversal
+steps = await alice_v.to("follows")
+if steps:
+    neighbor_v = steps[0].vertex()
+    print(f"Alice follows: {neighbor_v.id}")
+
+# 2. Reverse traversal (incoming links)
+rev_steps = await neighbor_v.from_("follows")
+if rev_steps:
+    creator_v = rev_steps[0].vertex()  # returns Alice!
+    print(f"Alice was found by reverse traversal: {creator_v.id}")
+
+# 3. Direct Edge Mutations via Objects/Steps
+if rev_steps:
+    new_edge = await rev_steps[0].add_edge_to(to_id="p_5", edge_table="likes")
+    print(f"Added edge: {new_edge.from_id} -> {new_edge.to_id}")
+
+# 4. Direct Vertex/Edge Deletion
+# Deleting a vertex automatically cascade-deletes all connecting edges in the database
+await neighbor_v.delete(user_id="admin_1")
+```
+
+### Path Traversal
+Retrieve all reachable paths up to a specified depth (default 3) starting from a vertex:
+```python
+paths = await client.traverse(
+    realm="tenant_1", 
+    start_table="users", 
+    start_id="u_1", 
+    edge_tables=["likes", "follows"], 
+    max_depth=3
+)
+for p in paths:
+    print(f"Path taken: {p['path']} via relations: {p['edge_path']}")
+```
+
+### Shortest Path
+Find the shortest path between two vertices, preventing cycles:
+```python
+sp = await client.shortest_path(
+    realm="tenant_1",
+    start_table="users",
+    start_id="u_1",
+    target_table="posts",
+    target_id="p_5",
+    edge_tables=["follows", "likes"]
+)
+if sp:
+    print(f"Shortest path depth: {sp['depth']}, steps: {sp['path']}")
+```
+
+---
+
+## Shadow Auditing & Session User Mapping
+
+Auditing works entirely inside PostgreSQL triggers. To attribute a change to a user:
+1. When calling Python operations (`add_vertex`, `upsert_edge`, `delete_vertex`, etc.), pass the `user_id` keyword argument.
+2. The library executes `SELECT set_config('app.current_user_id', user_id, true)` in the current transaction block.
+3. The database trigger automatically maps this value into the `{table_name}_audit` table.
+A query to `{table_name}_audit` returns the modification history:
+```sql
+SELECT audit_id, realm, action, changed_by, changed_at, old_row, new_row 
+FROM users_audit;
+```
+
+---
+
+## Schema-Per-Realm (Physical Namespace Isolation)
+
+By default, `post-graph` uses a single shared set of tables and isolates data logically using a `realm` column. If you require physical data isolation, enable the `schema_per_realm` parameter on client initialization:
+
+```python
+# Initialize Async Client with physical namespace isolation
+client = AsyncPostGraph(dsn=db_url, schema_per_realm=True)
+
+# Create vertex table under specific realm schema namespace 'tenant_a'
+await client.create_vertex_table("users", realm="tenant_a")
+```
+
+When enabled:
+1. Every realm has its own dedicated schema namespace (e.g. `CREATE SCHEMA IF NOT EXISTS "tenant_a"`).
+2. All vertex, edge, and shadow audit tables for a realm are stored physically inside that schema (e.g., `"tenant_a"."users"` and `"tenant_a"."users_audit"`).
+3. Database level triggers are completely isolated per schema namespace.
+4. Schema-specific metadata catalog lookups verify table links locally inside the target schema namespace.
+