vention-storage 0.6__tar.gz → 0.6.3__tar.gz

vention_storage-0.6/README.md → vention_storage-0.6.3/PKG-INFO

@@ -1,3 +1,35 @@
+Metadata-Version: 2.4
+Name: vention-storage
+Version: 0.6.3
+Summary: A framework for storing and managing component and application data for machine apps.
+License: Proprietary
+Author: VentionCo
+Requires-Python: >=3.10,<3.11
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Requires-Dist: annotated-doc (==0.0.4) ; python_version == "3.10"
+Requires-Dist: annotated-types (==0.7.0) ; python_version == "3.10"
+Requires-Dist: anyio (==4.12.1) ; python_version == "3.10"
+Requires-Dist: click (==8.3.1) ; python_version == "3.10"
+Requires-Dist: colorama (==0.4.6) ; python_version == "3.10" and platform_system == "Windows"
+Requires-Dist: exceptiongroup (==1.3.1) ; python_version == "3.10"
+Requires-Dist: fastapi (==0.121.1) ; python_version == "3.10"
+Requires-Dist: greenlet (==3.3.1) ; python_version == "3.10" and (platform_machine == "aarch64" or platform_machine == "ppc64le" or platform_machine == "x86_64" or platform_machine == "amd64" or platform_machine == "AMD64" or platform_machine == "win32" or platform_machine == "WIN32")
+Requires-Dist: h11 (==0.16.0) ; python_version == "3.10"
+Requires-Dist: idna (==3.11) ; python_version == "3.10"
+Requires-Dist: pydantic (==2.12.5) ; python_version == "3.10"
+Requires-Dist: pydantic-core (==2.41.5) ; python_version == "3.10"
+Requires-Dist: python-multipart (==0.0.20) ; python_version == "3.10"
+Requires-Dist: sqlalchemy (==2.0.46) ; python_version == "3.10"
+Requires-Dist: sqlmodel (==0.0.27) ; python_version == "3.10"
+Requires-Dist: starlette (==0.49.3) ; python_version == "3.10"
+Requires-Dist: typing-extensions (==4.15.0) ; python_version == "3.10"
+Requires-Dist: typing-inspection (==0.4.2) ; python_version == "3.10"
+Requires-Dist: uvicorn (==0.35.0) ; python_version == "3.10"
+Requires-Dist: vention-communication (==0.3.0) ; python_version == "3.10"
+Description-Content-Type: text/markdown
+
 # Vention Storage
 
 A framework for storing and managing component and application data with persistence, validation, and audit trails for machine applications.
@@ -192,8 +224,47 @@ user_accessor.delete(user.id, actor="admin")
 
 # Restore (for soft-deleted models)
 user_accessor.restore(user.id, actor="admin")
-```
 
+# Find users by exact match
+users = user_accessor.find(user_accessor.where.email == "alice@example.com")
+
+# Multiple conditions (AND logic)
+users = user_accessor.find(
+    user_accessor.where.name == "Alice",
+    user_accessor.where.email == "alice@example.com"
+)
+
+# Comparison operators
+adults = user_accessor.find(user_accessor.where.age >= 18)
+recent = user_accessor.find(user_accessor.where.created_at > cutoff_date)
+
+# String operations
+smiths = user_accessor.find(user_accessor.where.name.contains("Smith"))
+gmail_users = user_accessor.find(user_accessor.where.email.endswith("@gmail.com"))
+search = user_accessor.find(user_accessor.where.name.ilike("%alice%"))  # case-insensitive
+
+# Collection check
+admins = user_accessor.find(user_accessor.where.role.in_(["admin", "superadmin"]))
+
+# Null checks
+unverified = user_accessor.find(user_accessor.where.verified_at.is_(None))
+verified = user_accessor.find(user_accessor.where.verified_at.isnot(None))
+
+# With pagination and sorting
+page = user_accessor.find(
+    user_accessor.where.status == "active",
+    limit=10,
+    offset=20,
+    order_by="created_at",
+    order_desc=True
+)
+
+# Include soft-deleted records
+all_users = user_accessor.find(
+    user_accessor.where.role == "admin",
+    include_deleted=True
+)
+```
 
 ### Using ConnectRPC Client
 
@@ -263,8 +334,73 @@ export async function listUsers() {
   });
   return res.records;
 }
+
+// Find by exact match
+export async function findUserByEmail(email: string) {
+  const res = await client.usersFindRecords({
+    filters: [
+      { field: "email", operation: "eq", value: email }
+    ]
+  });
+  return res.records;
+}
+
+// Find with multiple conditions (AND logic)
+export async function findActiveAdmins() {
+  const res = await client.usersFindRecords({
+    filters: [
+      { field: "role", operation: "eq", value: "admin" },
+      { field: "age", operation: "gte", value: "18" }
+    ]
+  });
+  return res.records;
+}
+
+// Find with null checks
+export async function findUnverifiedUsers() {
+  const res = await client.usersFindRecords({
+    filters: [
+      { field: "verified_at", operation: "is_null" }
+    ]
+  });
+  return res.records;
+}
+
+// Complex query example
+export async function findRecentPremiumUsers(cutoffDate: string) {
+  const res = await client.usersFindRecords({
+    filters: [
+      { field: "subscription", operation: "in", value: ["premium", "enterprise"] },
+      { field: "created_at", operation: "gte", value: cutoffDate },
+      { field: "email_verified", operation: "is_not_null" }
+    ],
+    limit: 50,
+    orderBy: "created_at",
+    orderDesc: true
+  });
+  return res.records;
+}
 ```
 
+### Filter Operations Reference
+
+| Operation      | Description                          |
+|----------------|--------------------------------------|
+| `eq`           | Exact match                          |
+| `ne`           | Not equal to value                   |
+| `gt`           | Greater than value                   |
+| `gte`          | Greater than or equal                |
+| `lt`           | Less than value                      |
+| `lte`          | Less than or equal                   |
+| `in`           | Value in array                       |
+| `not_in`       | Value not in array                   |
+| `contains`     | Field contains substring             |
+| `starts_with`  | Field starts with prefix             |
+| `ends_with`    | Field ends with suffix               |
+| `like`         | Case-insensitive pattern match       |
+| `is_null`      | Field is null (no value needed)      |
+| `is_not_null`  | Field is not null (no value needed)  |
+
 
 ## 📖 API Reference
 
@@ -355,4 +491,4 @@ class AuditLog(SQLModel, table=True):
 - **Diagram endpoint fails** → Ensure Graphviz + sqlalchemy-schemadisplay are installed.
 - **No audit actor shown** → Provide X-User header in API requests.
 - **Soft delete not working** → Your model must have a `deleted_at` field.
-- **Restore fails** → Ensure `integrity_check=True` passes when restoring backups.
+- **Restore fails** → Ensure `integrity_check=True` passes when restoring backups.

vention_storage-0.6/PKG-INFO → vention_storage-0.6.3/README.md

@@ -1,18 +1,3 @@
-Metadata-Version: 2.4
-Name: vention-storage
-Version: 0.6
-Summary: A framework for storing and managing component and application data for machine apps.
-License: Proprietary
-Author: VentionCo
-Requires-Python: >=3.10,<3.11
-Classifier: License :: Other/Proprietary License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Requires-Dist: python-multipart (>=0.0.20,<0.0.21)
-Requires-Dist: sqlmodel (==0.0.27)
-Requires-Dist: vention-communication (>=0.2.2,<0.3.0)
-Description-Content-Type: text/markdown
-
 # Vention Storage
 
 A framework for storing and managing component and application data with persistence, validation, and audit trails for machine applications.
@@ -207,8 +192,47 @@ user_accessor.delete(user.id, actor="admin")
 
 # Restore (for soft-deleted models)
 user_accessor.restore(user.id, actor="admin")
-```
 
+# Find users by exact match
+users = user_accessor.find(user_accessor.where.email == "alice@example.com")
+
+# Multiple conditions (AND logic)
+users = user_accessor.find(
+    user_accessor.where.name == "Alice",
+    user_accessor.where.email == "alice@example.com"
+)
+
+# Comparison operators
+adults = user_accessor.find(user_accessor.where.age >= 18)
+recent = user_accessor.find(user_accessor.where.created_at > cutoff_date)
+
+# String operations
+smiths = user_accessor.find(user_accessor.where.name.contains("Smith"))
+gmail_users = user_accessor.find(user_accessor.where.email.endswith("@gmail.com"))
+search = user_accessor.find(user_accessor.where.name.ilike("%alice%"))  # case-insensitive
+
+# Collection check
+admins = user_accessor.find(user_accessor.where.role.in_(["admin", "superadmin"]))
+
+# Null checks
+unverified = user_accessor.find(user_accessor.where.verified_at.is_(None))
+verified = user_accessor.find(user_accessor.where.verified_at.isnot(None))
+
+# With pagination and sorting
+page = user_accessor.find(
+    user_accessor.where.status == "active",
+    limit=10,
+    offset=20,
+    order_by="created_at",
+    order_desc=True
+)
+
+# Include soft-deleted records
+all_users = user_accessor.find(
+    user_accessor.where.role == "admin",
+    include_deleted=True
+)
+```
 
 ### Using ConnectRPC Client
 
@@ -278,8 +302,73 @@ export async function listUsers() {
   });
   return res.records;
 }
+
+// Find by exact match
+export async function findUserByEmail(email: string) {
+  const res = await client.usersFindRecords({
+    filters: [
+      { field: "email", operation: "eq", value: email }
+    ]
+  });
+  return res.records;
+}
+
+// Find with multiple conditions (AND logic)
+export async function findActiveAdmins() {
+  const res = await client.usersFindRecords({
+    filters: [
+      { field: "role", operation: "eq", value: "admin" },
+      { field: "age", operation: "gte", value: "18" }
+    ]
+  });
+  return res.records;
+}
+
+// Find with null checks
+export async function findUnverifiedUsers() {
+  const res = await client.usersFindRecords({
+    filters: [
+      { field: "verified_at", operation: "is_null" }
+    ]
+  });
+  return res.records;
+}
+
+// Complex query example
+export async function findRecentPremiumUsers(cutoffDate: string) {
+  const res = await client.usersFindRecords({
+    filters: [
+      { field: "subscription", operation: "in", value: ["premium", "enterprise"] },
+      { field: "created_at", operation: "gte", value: cutoffDate },
+      { field: "email_verified", operation: "is_not_null" }
+    ],
+    limit: 50,
+    orderBy: "created_at",
+    orderDesc: true
+  });
+  return res.records;
+}
 ```
 
+### Filter Operations Reference
+
+| Operation      | Description                          |
+|----------------|--------------------------------------|
+| `eq`           | Exact match                          |
+| `ne`           | Not equal to value                   |
+| `gt`           | Greater than value                   |
+| `gte`          | Greater than or equal                |
+| `lt`           | Less than value                      |
+| `lte`          | Less than or equal                   |
+| `in`           | Value in array                       |
+| `not_in`       | Value not in array                   |
+| `contains`     | Field contains substring             |
+| `starts_with`  | Field starts with prefix             |
+| `ends_with`    | Field ends with suffix               |
+| `like`         | Case-insensitive pattern match       |
+| `is_null`      | Field is null (no value needed)      |
+| `is_not_null`  | Field is not null (no value needed)  |
+
 
 ## 📖 API Reference
 
@@ -370,4 +459,4 @@ class AuditLog(SQLModel, table=True):
 - **Diagram endpoint fails** → Ensure Graphviz + sqlalchemy-schemadisplay are installed.
 - **No audit actor shown** → Provide X-User header in API requests.
 - **Soft delete not working** → Your model must have a `deleted_at` field.
-- **Restore fails** → Ensure `integrity_check=True` passes when restoring backups.
+- **Restore fails** → Ensure `integrity_check=True` passes when restoring backups.

vention_storage-0.6.3/pyproject.toml

@@ -0,0 +1,117 @@
+[tool.poetry]
+name = "vention-storage"
+version = "0.6.3"
+description = "A framework for storing and managing component and application data for machine apps."
+authors = [ "VentionCo" ]
+readme = "README.md"
+license = "Proprietary"
+
+  [[tool.poetry.packages]]
+  include = "storage"
+  from = "src"
+
+  [tool.poetry.dependencies]
+  python = ">=3.10,<3.11"
+
+    [tool.poetry.dependencies.annotated-doc]
+    version = "0.0.4"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.annotated-types]
+    version = "0.7.0"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.anyio]
+    version = "4.12.1"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.click]
+    version = "8.3.1"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.colorama]
+    version = "0.4.6"
+    markers = 'python_version == "3.10" and platform_system == "Windows"'
+    optional = false
+
+    [tool.poetry.dependencies.exceptiongroup]
+    version = "1.3.1"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.fastapi]
+    version = "0.121.1"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.greenlet]
+    version = "3.3.1"
+    markers = 'python_version == "3.10" and (platform_machine == "aarch64" or platform_machine == "ppc64le" or platform_machine == "x86_64" or platform_machine == "amd64" or platform_machine == "AMD64" or platform_machine == "win32" or platform_machine == "WIN32")'
+    optional = false
+
+    [tool.poetry.dependencies.h11]
+    version = "0.16.0"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.idna]
+    version = "3.11"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.pydantic-core]
+    version = "2.41.5"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.pydantic]
+    version = "2.12.5"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.python-multipart]
+    version = "0.0.20"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.sqlalchemy]
+    version = "2.0.46"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.sqlmodel]
+    version = "0.0.27"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.starlette]
+    version = "0.49.3"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.typing-extensions]
+    version = "4.15.0"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.typing-inspection]
+    version = "0.4.2"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.uvicorn]
+    version = "0.35.0"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+    [tool.poetry.dependencies.vention-communication]
+    version = "0.3.0"
+    markers = 'python_version == "3.10"'
+    optional = false
+
+[tool.poetry.group.dev]
+dependencies = { }

{vention_storage-0.6 → vention_storage-0.6.3}/src/storage/accessor.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from contextlib import contextmanager
+from functools import reduce
 from typing import (
     Any,
     Callable,
@@ -15,6 +16,7 @@ from typing import (
 )
 
 from sqlmodel import SQLModel, Session, select
+from sqlmodel.sql.expression import SelectOfScalar
 
 from storage.auditor import audit_operation
 from storage import database
@@ -25,6 +27,48 @@ from storage.utils import ModelType, utcnow, Operation
 WriteResult = TypeVar("WriteResult")
 
 
+def _apply_conditions(statement: SelectOfScalar[ModelType], conditions: tuple[Any, ...]) -> SelectOfScalar[ModelType]:
+    """Apply filter conditions to a select statement."""
+    return reduce(lambda stmt, cond: stmt.where(cond), conditions, statement)
+
+
+def _apply_soft_delete_filter(
+    statement: SelectOfScalar[ModelType],
+    model: Type[ModelType],
+    has_soft_delete: bool,
+    include_deleted: bool,
+) -> SelectOfScalar[ModelType]:
+    """Apply soft delete filter if applicable."""
+    if not has_soft_delete or include_deleted:
+        return statement
+    return statement.where(getattr(model, "deleted_at").is_(None))
+
+
+def _apply_ordering(
+    statement: SelectOfScalar[ModelType],
+    model: Type[ModelType],
+    order_by: Optional[str],
+    order_desc: bool,
+) -> SelectOfScalar[ModelType]:
+    """Apply ordering to a select statement."""
+    if not order_by:
+        return statement
+    field = getattr(model, order_by, None)
+    if field is None:
+        raise ValueError(f"Field '{order_by}' not found on {model.__name__}")
+    return statement.order_by(field.desc() if order_desc else field)
+
+
+def _apply_pagination(
+    statement: SelectOfScalar[ModelType],
+    limit: Optional[int],
+    offset: int,
+) -> SelectOfScalar[ModelType]:
+    """Apply pagination to a select statement."""
+    limited = statement.limit(limit) if limit is not None else statement
+    return limited.offset(offset) if offset > 0 else limited
+
+
 class ModelAccessor(Generic[ModelType]):
     """
     Accessor for a single SQLModel type with:
@@ -47,6 +91,8 @@ class ModelAccessor(Generic[ModelType]):
         self._hooks: HookRegistry[ModelType] = HookRegistry()
         self._has_soft_delete = hasattr(model, "deleted_at")
         self._enable_auditing = enable_auditing
+        # Field proxy for type-safe filtering: accessor.where.field_name
+        self.where = model
 
     # ---------- Hook decorators ----------
     def before_insert(self) -> Callable[[HookFn[ModelType]], HookFn[ModelType]]:
@@ -73,9 +119,7 @@ class ModelAccessor(Generic[ModelType]):
         with database.use_session(session):
             self._hooks.emit(event, session=session, instance=instance)
 
-    def _audit_create_operation(
-        self, *, session: Session, instance: ModelType, actor: str
-    ) -> None:
+    def _audit_create_operation(self, *, session: Session, instance: ModelType, actor: str) -> None:
         """Audit a create operation."""
         if not self._enable_auditing:
             return
@@ -90,7 +134,7 @@ class ModelAccessor(Generic[ModelType]):
         )
 
     def _run_write(self, fn: Callable[[Session], WriteResult]) -> WriteResult:
-        """Run a write op using the current session if present, else open a transaction."""
+        """Run a write operation using the current session if present, else open a transaction."""
         existing = database.CURRENT_SESSION.get()
         if existing is not None:
             return fn(existing)
@@ -119,12 +163,83 @@ class ModelAccessor(Generic[ModelType]):
                     return None
             return cast(ModelType, obj)
 
-    def all(self, *, include_deleted: bool = False) -> List[ModelType]:
-        """Get all models."""
+    def all(
+        self,
+        *,
+        include_deleted: bool = False,
+        limit: Optional[int] = None,
+        offset: int = 0,
+        order_by: Optional[str] = None,
+        order_desc: bool = False,
+    ) -> List[ModelType]:
+        """Get all models with optional pagination and sorting.
+
+        Args:
+            include_deleted: Whether to include soft-deleted records
+            limit: Maximum number of records to return (None = no limit)
+            offset: Number of records to skip (for pagination)
+            order_by: Field name to sort by (must exist on model)
+            order_desc: If True, sort descending; otherwise ascending
+
+        Returns:
+            List of model instances
+
+        Raises:
+            ValueError: If order_by field doesn't exist on the model
+        """
         with self._read_session() as session:
             statement = select(self.model)
-            if self._has_soft_delete and not include_deleted:
-                statement = statement.where(getattr(self.model, "deleted_at").is_(None))
+            statement = _apply_soft_delete_filter(statement, self.model, self._has_soft_delete, include_deleted)
+            statement = _apply_ordering(statement, self.model, order_by, order_desc)
+            statement = _apply_pagination(statement, limit, offset)
+
+            return cast(List[ModelType], session.exec(statement).all())
+
+    def find(
+        self,
+        *conditions: Any,
+        include_deleted: bool = False,
+        limit: Optional[int] = None,
+        offset: int = 0,
+        order_by: Optional[str] = None,
+        order_desc: bool = False,
+    ) -> List[ModelType]:
+        """Find records matching all given filter conditions.
+
+        Args:
+            *conditions: SQLAlchemy filter conditions using accessor.where.field_name
+            include_deleted: Whether to include soft-deleted records
+            limit: Maximum number of records to return (None = no limit)
+            offset: Number of records to skip (for pagination)
+            order_by: Field name to sort by (must exist on model)
+            order_desc: If True, sort descending; otherwise ascending
+
+        Returns:
+            List of model instances matching all conditions
+
+        Example:
+            # Find active users over 18
+            users = user_accessor.find(
+                user_accessor.where.age >= 18,
+                user_accessor.where.status == "active",
+                limit=10
+            )
+
+            # String operations
+            users = user_accessor.find(
+                user_accessor.where.name.contains("Smith")
+            )
+
+        Raises:
+            ValueError: If order_by field doesn't exist on the model
+        """
+        with self._read_session() as session:
+            statement = select(self.model)
+            statement = _apply_conditions(statement, conditions)
+            statement = _apply_soft_delete_filter(statement, self.model, self._has_soft_delete, include_deleted)
+            statement = _apply_ordering(statement, self.model, order_by, order_desc)
+            statement = _apply_pagination(statement, limit, offset)
+
             return cast(List[ModelType], session.exec(statement).all())
 
     # ---------- Writes ----------
@@ -227,9 +342,7 @@ class ModelAccessor(Generic[ModelType]):
         return self._run_write(write_operation)
 
     # ---------- Batch helpers ----------
-    def insert_many(
-        self, objs: Sequence[ModelType], *, actor: str = "internal"
-    ) -> List[ModelType]:
+    def insert_many(self, objs: Sequence[ModelType], *, actor: str = "internal") -> List[ModelType]:
         """Insert multiple models."""
 
         def write_operation(session: Session) -> List[ModelType]:
@@ -257,9 +370,7 @@ class ModelAccessor(Generic[ModelType]):
                 if obj is None:
                     continue
                 self._emit("before_delete", session=session, instance=obj)
-                op_name, before_payload, after_payload = _soft_or_hard_delete(
-                    session, obj
-                )
+                op_name, before_payload, after_payload = _soft_or_hard_delete(session, obj)
                 if self._enable_auditing:
                     audit_operation(
                         session=session,
@@ -277,9 +388,7 @@ class ModelAccessor(Generic[ModelType]):
         return self._run_write(write_operation)
 
 
-def _soft_or_hard_delete(
-    session: Session, instance: SQLModel
-) -> tuple[Operation, dict[str, Any], dict[str, Any] | None]:
+def _soft_or_hard_delete(session: Session, instance: SQLModel) -> tuple[Operation, dict[str, Any], dict[str, Any] | None]:
     """Soft delete if model defines `deleted_at`, else hard delete."""
     before_payload = instance.model_dump()
     if hasattr(instance, "deleted_at"):