vention-storage 0.5.4__py3-none-any.whl → 0.6.0__py3-none-any.whl

{vention_storage-0.5.4.dist-info → vention_storage-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: vention-storage
-Version: 0.5.4
+Version: 0.6.0
 Summary: A framework for storing and managing component and application data for machine apps.
 License: Proprietary
 Author: VentionCo
@@ -8,10 +8,9 @@ Requires-Python: >=3.10,<3.11
 Classifier: License :: Other/Proprietary License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
-Requires-Dist: fastapi (==0.121.1)
 Requires-Dist: python-multipart (>=0.0.20,<0.0.21)
 Requires-Dist: sqlmodel (==0.0.27)
-Requires-Dist: uvicorn (>=0.35.0,<0.36.0)
+Requires-Dist: vention-communication (>=0.2.2,<0.3.0)
 Description-Content-Type: text/markdown
 
 # Vention Storage
@@ -35,8 +34,8 @@ A framework for storing and managing component and application data with persist
 - Strong typing & validation via SQLModel
 - Lifecycle hooks before/after insert, update, delete
 - Soft delete with `deleted_at` fields
-- REST API generation with Create, Read, Update, Delete + audit
-- Health & monitoring endpoints (audit log, schema diagram)
+- ConnectRPC bundle generation with Create, Read, Update, Delete + audit
+- Health & monitoring actions (audit log, schema diagram)
 - Batch operations for insert/delete
 - Session management with smart reuse & transactions
 - Bootstrap system for one-command setup
@@ -51,7 +50,7 @@ Vention Storage is a component-based persistence layer for machine apps:
 - **ModelAccessor** → Strongly-typed Create, Read, Update, Delete interface for your SQLModel classes
 - **Hooks** → Functions that run before/after Create, Read, Update, Delete operations
 - **AuditLog** → Automatically records all data mutations
-- **Routers** → Auto-generated FastAPI endpoints for Create, Read, Update, Delete + database management
+- **RpcBundle** → Auto-generated ConnectRPC bundle with Create, Read, Update, Delete + database management actions
 
 ## ⚙️ Installation & Setup
 
@@ -76,15 +75,16 @@ pip install sqlalchemy-schemadisplay
 
 ## 🚀 Quickstart Tutorial
 
-Define a model, bootstrap storage, and get full Create, Read, Update, Delete endpoints in minutes:
+Define a model, bootstrap storage, and get full Create, Read, Update, Delete RPC actions in minutes:
 
 ```python
 from datetime import datetime
 from typing import Optional
 from sqlmodel import Field, SQLModel
-from fastapi import FastAPI
+from communication.app import VentionApp
 from storage.bootstrap import bootstrap
 from storage.accessor import ModelAccessor
+from storage.vention_communication import build_storage_bundle
 
 class User(SQLModel, table=True):
     id: Optional[int] = Field(default=None, primary_key=True)
@@ -92,18 +92,27 @@ class User(SQLModel, table=True):
     email: str
     deleted_at: Optional[datetime] = Field(default=None, index=True)
 
-app = FastAPI()
-user_accessor = ModelAccessor(User, "users")
-
+# Initialize database
 bootstrap(
-    app,
-    accessors=[user_accessor],
     database_url="sqlite:///./my_app.db",
     create_tables=True
 )
+
+# Create accessor
+user_accessor = ModelAccessor(User, "users")
+
+# Build RPC bundle and add to app
+app = VentionApp(name="my-app")
+storage_bundle = build_storage_bundle(
+    accessors=[user_accessor],
+    max_records_per_model=100,
+    enable_db_actions=True
+)
+app.add_bundle(storage_bundle)
+app.finalize()
 ```
 
-➡️ You now have Create, Read, Update, Delete, audit, backup, and CSV endpoints at `/users` and `/db`.
+➡️ You now have Create, Read, Update, Delete, audit, backup, and CSV actions available via ConnectRPC.
 
 ## 🛠 How-to Guides
 
@@ -115,35 +124,46 @@ bootstrap(
 
 product_accessor = ModelAccessor(Product, "products")
 
-bootstrap(
-    app,
+# Build bundle with multiple accessors
+storage_bundle = build_storage_bundle(
     accessors=[user_accessor, product_accessor],
-    database_url="sqlite:///./my_app.db",
-    create_tables=True,
     max_records_per_model=100,
-    enable_db_router=True
+    enable_db_actions=True
 )
+app.add_bundle(storage_bundle)
 ```
 
 ### Export to CSV
 
 ```python
-response = requests.get("http://localhost:8000/db/export.zip")
+# Using ConnectRPC client
+from communication.client import ConnectClient
+
+client = ConnectClient("http://localhost:8000")
+response = await client.call("Database_ExportZip", {})
 with open("backup.zip", "wb") as f:
-    f.write(response.content)
+    f.write(response.data)
 ```
 
 ### Backup & Restore
 
 ```python
 # Backup
-r = requests.get("http://localhost:8000/db/backup.sqlite")
-with open("backup.sqlite", "wb") as f: f.write(r.content)
+backup_response = await client.call("Database_BackupSqlite", {})
+with open(backup_response.filename, "wb") as f:
+    f.write(backup_response.data)
 
 # Restore
 with open("backup.sqlite", "rb") as f:
-    files = {"file": ("backup.sqlite", f, "application/x-sqlite3")}
-    requests.post("http://localhost:8000/db/restore", files=files)
+    restore_response = await client.call(
+        "Database_RestoreSqlite",
+        {
+            "bytes": f.read(),
+            "filename": "backup.sqlite",
+            "integrity_check": True,
+            "dry_run": False
+        }
+    )
 ```
 
 ### Use Lifecycle Hooks
@@ -190,52 +210,73 @@ user_accessor.restore(user.id, actor="admin")
 ```
 
 
-### Using the REST API
+### Using ConnectRPC Client
 
-Once bootstrapped, each `ModelAccessor` automatically exposes full CRUD endpoints.
+Once the bundle is added to your `VentionApp`, each `ModelAccessor` automatically exposes full CRUD actions via ConnectRPC.
 
-Example: interacting with the `/users` API.
+Example: interacting with the `Users` RPC actions.
 
 ```typescript
-import axios from "axios";
+import { createPromiseClient } from "@connectrpc/connect";
+import { createConnectTransport } from "@connectrpc/connect-web";
 
-const api = axios.create({
-  baseURL: "http://localhost:8000", // your backend url
-  headers: { "X-User": "operator" }, // used in audit logs
+const transport = createConnectTransport({
+  baseUrl: "http://localhost:8000",
 });
 
+const client = createPromiseClient(YourServiceClient, transport);
+
 // Create
 export async function createUser(name: string, email: string) {
-  const res = await api.post("/users/", { name, email });
-  return res.data;
+  const res = await client.usersCreateRecord({
+    record: { name, email },
+    actor: "operator"
+  });
+  return res.record;
 }
 
 // Read
 export async function getUser(id: number) {
-  const res = await api.get(`/users/${id}`);
-  return res.data;
+  const res = await client.usersGetRecord({
+    recordId: id,
+    includeDeleted: false
+  });
+  return res.record;
 }
 
 // Update
 export async function updateUser(id: number, name: string) {
-  const res = await api.put(`/users/${id}`, { name });
-  return res.data;
+  const res = await client.usersUpdateRecord({
+    recordId: id,
+    record: { name },
+    actor: "operator"
+  });
+  return res.record;
 }
 
 // Delete (soft delete if model supports deleted_at)
 export async function deleteUser(id: number) {
-  await api.delete(`/users/${id}`);
+  await client.usersDeleteRecord({
+    recordId: id,
+    actor: "operator"
+  });
 }
 
 // Restore
 export async function restoreUser(id: number) {
-  await api.post(`/users/${id}/restore`);
+  const res = await client.usersRestoreRecord({
+    recordId: id,
+    actor: "operator"
+  });
+  return res.record;
 }
 
 // List
 export async function listUsers() {
-  const res = await api.get("/users/");
-  return res.data;
+  const res = await client.usersListRecords({
+    includeDeleted: false
+  });
+  return res.records;
 }
 ```
 
@@ -246,20 +287,36 @@ export async function listUsers() {
 
 ```python
 def bootstrap(
-    app: FastAPI,
     *,
-    accessors: Iterable[ModelAccessor[Any]],
     database_url: Optional[str] = None,
     create_tables: bool = True,
-    max_records_per_model: Optional[int] = 5,
-    enable_db_router: bool = True,
 ) -> None
 ```
 
+Initialize the database engine and optionally create tables. This function performs environment setup only.
+
+### build_storage_bundle
+
+```python
+def build_storage_bundle(
+    *,
+    accessors: Sequence[ModelAccessor[Any]],
+    max_records_per_model: Optional[int] = 5,
+    enable_db_actions: bool = True,
+) -> RpcBundle
+```
+
+Build a ConnectRPC RpcBundle exposing CRUD and database utilities. Returns an `RpcBundle` that can be added to a `VentionApp` using `app.add_bundle()`.
+
 ### ModelAccessor
 
 ```python
-ModelAccessor(model: Type[ModelType], component_name: str)
+ModelAccessor(
+    model: Type[ModelType],
+    component_name: str,
+    *,
+    enable_auditing: bool = True,
+)
 ```
 
 **Read**
@@ -284,10 +341,8 @@ ModelAccessor(model: Type[ModelType], component_name: str)
 - `@accessor.before_delete()`
 - `@accessor.after_delete()`
 
-### Routers
-
-- `build_crud_router(accessor, max_records=100) -> APIRouter`
-- `build_db_router(audit_default_limit=100, audit_max_limit=1000) -> APIRouter`
+**Parameters**
+- `enable_auditing`: If `False`, disables audit logging for this accessor. Useful for models that shouldn't be audited (e.g., audit logs themselves). Defaults to `True`.
 
 ### Database Helpers
 

vention_storage-0.6.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+storage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+storage/accessor.py,sha256=QgLnju-31jBprLtFMyAy8duKZKAshO8Rngd5cBjduhY,10879
+storage/auditor.py,sha256=tsvsb9qlHdcknY5OAXRZBMcN4nFDKtN3Ln1LfgozJrw,2090
+storage/bootstrap.py,sha256=rZBXQF4M-Lm4Rw2T74M4-swMBgAWEts16v9mG64t2hM,846
+storage/crud_service.py,sha256=9XUkOjiw16O9UzRYPBUV1NYUu34-pEbYTp310xopgkU,5281
+storage/database.py,sha256=BGRnlH0qBVnYffp0F1TCWGb6OS8cdlMmEJ1-LeHH4oc,3184
+storage/database_service.py,sha256=pUhS3LfSswIfr7wlIcUbO3uVuT_GzfKh4QwOuQrwf1k,7868
+storage/hooks.py,sha256=rMK8R-VO0B7caZn9HtTlcetx0KQMvsl1Aq-t9mbFA4Q,1298
+storage/io_helpers.py,sha256=oTyVXRdD4eVuqpIOFNh_4ULqiNJ46pNCT38he1dzMBg,5528
+storage/utils.py,sha256=AV8d1WQmdBLAnpoGJX3c8th5_mYFAei6d_ZxDG5QOAE,1320
+storage/vention_communication.py,sha256=sBtwA5SLBSq0-fnQgwL1UmQwloSSnbv-pS2Iiv32o3g,15421
+vention_storage-0.6.0.dist-info/METADATA,sha256=xWgWEcwA-9z4zVJepXBTTUFmhngRQan7fkxuLV_uAtk,9858
+vention_storage-0.6.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+vention_storage-0.6.0.dist-info/RECORD,,

{vention_storage-0.5.4.dist-info → vention_storage-0.6.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 1.9.1
+Generator: poetry-core 2.2.1
 Root-Is-Purelib: true
 Tag: py3-none-any

storage/router_database.py

@@ -1,275 +0,0 @@
-from __future__ import annotations
-
-from datetime import datetime, timezone
-from typing import Dict, List, Optional
-from pathlib import Path
-
-from fastapi import APIRouter, HTTPException, Query, Response, UploadFile, File
-from sqlmodel import SQLModel, select
-from sqlalchemy import desc
-
-from storage import database, io_helpers
-from storage.auditor import AuditLog
-from storage.utils import Operation
-
-from storage.io_helpers import (
-    discover_user_tables,
-    build_export_zip_bytes,
-    db_file_path,
-    build_backup_bytes,
-    validate_sqlite_file,
-    safe_unlink,
-)
-
-__all__ = ["build_db_router"]
-
-
-def build_db_router(
-    *,
-    audit_default_limit: int = 100,
-    audit_max_limit: int = 1000,
-) -> APIRouter:
-    """
-    Build a FastAPI router exposing database-wide utilities.
-
-    Endpoints:
-      - /db/health          : Verify DB engine is available
-      - /db/audit           : Query audit logs (filters + pagination)
-      - /db/diagram.svg     : Schema diagram (requires Graphviz)
-      - /db/export.zip      : CSV export (one CSV per table)
-      - /db/backup.sqlite   : Full SQLite backup file
-      - /db/restore         : Upload and restore a .sqlite backup (atomic replace)
-    """
-    router = APIRouter(prefix="/db", tags=["db"])
-
-    @router.get("/health")
-    def health() -> Dict[str, str]:
-        """
-        Check database connectivity.
-
-        Returns:
-            dict: {"status": "ok"} if the database engine can be initialized.
-        """
-        _ = database.get_engine()
-        return {"status": "ok"}
-
-    @router.get("/audit")
-    def read_audit(
-        component: Optional[str] = Query(None, description="Filter by component name"),
-        record_id: Optional[int] = Query(None, description="Filter by record ID"),
-        actor: Optional[str] = Query(None, description="Filter by actor identifier"),
-        operation: Optional[Operation] = Query(
-            None, description="Filter by operation type"
-        ),
-        since: Optional[datetime] = Query(
-            None, description="Include only logs on/after this timestamp"
-        ),
-        until: Optional[datetime] = Query(
-            None, description="Include only logs before this timestamp"
-        ),
-        limit: int = Query(
-            audit_default_limit,
-            ge=1,
-            le=audit_max_limit,
-            description="Maximum rows to return",
-        ),
-        offset: int = Query(
-            0, ge=0, description="Number of rows to skip (for pagination)"
-        ),
-    ) -> List[AuditLog]:
-        """
-        Query the audit log table.
-
-        Supports filtering by component, record_id, actor, operation,
-        and timestamp range, with pagination.
-
-        Args:
-            component (str, optional): Restrict to a specific component.
-            record_id (int, optional): Restrict to a specific record ID.
-            actor (str, optional): Restrict to a specific actor (user/system).
-            operation (Operation, optional): Restrict to a specific operation.
-            since (datetime, optional): Include only logs since this timestamp.
-            until (datetime, optional): Include only logs before this timestamp.
-            limit (int): Maximum number of logs to return (bounded by audit_max_limit).
-            offset (int): Number of rows to skip for pagination.
-
-        Returns:
-            List[AuditLog]: A list of audit log entries matching the criteria.
-        """
-        with database.use_session() as session:
-            statement = select(AuditLog)
-            if component:
-                statement = statement.where(AuditLog.component == component)
-            if record_id is not None:
-                statement = statement.where(AuditLog.record_id == record_id)
-            if actor:
-                statement = statement.where(AuditLog.actor == actor)
-            if operation:
-                statement = statement.where(AuditLog.operation == operation)
-            if since is not None:
-                statement = statement.where(AuditLog.timestamp >= since)
-            if until is not None:
-                statement = statement.where(AuditLog.timestamp < until)
-            statement = (
-                statement.order_by(desc(AuditLog.timestamp)).offset(offset).limit(limit)
-            )
-            rows: List[AuditLog] = session.exec(statement).all()
-            return rows
-
-    @router.get("/diagram.svg", response_class=Response)
-    def diagram_svg() -> Response:
-        """
-        Generate a database schema diagram in SVG format.
-
-        Requires `sqlalchemy-schemadisplay` and Graphviz to be installed.
-        The diagram reflects the current SQLModel metadata.
-
-        Returns:
-            Response: SVG image of the database schema.
-
-        Raises:
-            HTTPException 503: If required dependencies are missing
-                               or Graphviz is not available.
-        """
-        try:
-            # import here to avoid hard dependency if not used
-            from sqlalchemy_schemadisplay import create_schema_graph
-        except Exception as e:
-            raise HTTPException(
-                status_code=503,
-                detail=(
-                    "sqlalchemy-schemadisplay is required. "
-                    "Install with: pip install sqlalchemy-schemadisplay"
-                ),
-            ) from e
-
-        try:
-            graph = create_schema_graph(
-                engine=database.get_engine(),
-                metadata=SQLModel.metadata,
-                show_datatypes=True,
-                show_indexes=False,
-                concentrate=False,
-            )
-            return Response(content=graph.create_svg(), media_type="image/svg+xml")
-        except Exception as e:
-            msg = str(e).lower()
-            if "executable" in msg or "dot not found" in msg or "graphviz" in msg:
-                raise HTTPException(
-                    status_code=503,
-                    detail=(
-                        "Graphviz is required to render the diagram. "
-                        "Install it (e.g. brew install graphviz / apt-get install graphviz)."
-                    ),
-                ) from e
-            raise
-
-    @router.get("/export.zip")
-    def export_zip() -> Response:
-        """
-        Export the entire database as a ZIP archive.
-
-        The archive contains one CSV file per user-defined table found in SQLModel metadata.
-        SQLite internal tables (e.g., "sqlite_sequence") are excluded.
-
-        Returns:
-            Response: application/zip payload with "{table}.csv" entries.
-        """
-        headers = {"Content-Disposition": 'attachment; filename="export.zip"'}
-        try:
-            zip_bytes = build_export_zip_bytes(discover_user_tables())
-        except Exception as e:
-            raise HTTPException(
-                status_code=503, detail=f"Failed to build export.zip: {e}"
-            ) from e
-        return Response(
-            content=zip_bytes, media_type="application/zip", headers=headers
-        )
-
-    @router.get("/backup.sqlite")
-    def backup_sqlite() -> Response:
-        """
-        Create and return a consistent SQLite backup of the current database file.
-
-        Uses the SQLite Backup API for correctness.
-
-        Returns:
-            Response: application/x-sqlite3 payload with a `.sqlite` file.
-
-        Raises:
-            HTTPException 503: Operational failure creating the backup.
-        """
-        path = db_file_path()
-        headers = {
-            "Content-Disposition": f'attachment; filename="backup-{_backup_timestamp_slug()}.sqlite"'
-        }
-        try:
-            data = build_backup_bytes(path)
-        except Exception as e:
-            raise HTTPException(
-                status_code=503, detail=f"Failed to create backup: {e}"
-            ) from e
-        return Response(
-            content=data, media_type="application/x-sqlite3", headers=headers
-        )
-
-    @router.post("/restore")
-    def restore_sqlite(
-        file: UploadFile = File(..., description="SQLite .sqlite backup to restore"),
-        integrity_check: bool = Query(
-            True, description="Run PRAGMA integrity_check before replacing"
-        ),
-        dry_run: bool = Query(
-            False, description="Validate only; do not modify current database"
-        ),
-    ) -> Dict[str, object]:
-        """
-        Restore the database from an uploaded SQLite file by atomically replacing the current DB file.
-
-        Steps:
-          1. Save upload to a temporary path.
-          2. Validate header and (optionally) PRAGMA integrity_check.
-          3. If dry_run: report validation OK and exit.
-          4. Dispose engine connections and os.replace(temp, db_path).
-
-        Returns:
-            dict: {status: "ok", restored: bool, bytes: int}
-
-        Raises:
-            HTTPException 422: Invalid SQLite file or failed integrity check.
-            HTTPException 503: Operational failure during file I/O.
-        """
-        path = db_file_path()
-        db_dir = Path(path).resolve().parent
-        try:
-            tmp_path, total = io_helpers.save_upload_to_temp(file, db_dir)
-        except Exception as e:
-            raise HTTPException(503, f"Failed to save upload: {e}") from e
-
-        try:
-            validate_sqlite_file(tmp_path, run_integrity_check=integrity_check)
-        except ValueError as ve:
-            safe_unlink(tmp_path)
-            raise HTTPException(422, str(ve)) from ve
-        except Exception as e:
-            safe_unlink(tmp_path)
-            raise HTTPException(422, f"Invalid SQLite file: {e}") from e
-
-        if dry_run:
-            safe_unlink(tmp_path)
-            return {"status": "ok", "restored": False, "bytes": total}
-
-        try:
-            io_helpers.atomic_replace_db(tmp_path, Path(path))
-        except Exception as e:
-            safe_unlink(tmp_path)
-            raise HTTPException(503, f"Failed to replace database file: {e}") from e
-
-        return {"status": "ok", "restored": True, "bytes": total}
-
-    return router
-
-
-def _backup_timestamp_slug() -> str:
-    """Timestamp safe for filenames (UTC, no colons)."""
-    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")