altcodepro-polydb-python 2.5.9__py3-none-any.whl → 2.5.11__py3-none-any.whl

polydb/adapters/S3Adapter.py

@@ -11,9 +11,8 @@ import os
 import threading
 from typing import Any, Dict, List, Optional
 
-
 from ..base.ObjectStorageAdapter import ObjectStorageAdapter
-from ..errors import StorageError, ConnectionError
+from ..errors import ConnectionError, StorageError
 from ..retry import retry
 
 
@@ -72,7 +71,6 @@ class S3Adapter(ObjectStorageAdapter):
 
     def _ensure_bucket_exists(self):
         """Create bucket if it doesn't exist (safe for AWS + LocalStack)"""
-        import boto3
         from botocore.exceptions import ClientError
 
         if not self._client:

polydb/adapters/S3CompatibleAdapter.py

@@ -5,7 +5,7 @@ import threading
 from typing import Any, Dict, List, Optional
 
 from ..base.ObjectStorageAdapter import ObjectStorageAdapter
-from ..errors import StorageError, ConnectionError
+from ..errors import ConnectionError, StorageError
 from ..retry import retry
 
 

polydb/adapters/SQSAdapter.py

@@ -5,11 +5,10 @@ import os
 import threading
 from typing import Any, Dict, List
 
-
 from ..base.QueueAdapter import QueueAdapter
 from ..errors import ConnectionError, QueueError
-from ..retry import retry
 from ..json_safe import json_safe
+from ..retry import retry
 
 
 class SQSAdapter(QueueAdapter):

polydb/adapters/VercelBlobAdapter.py

@@ -1,5 +1,5 @@
-import os
 import mimetypes
+import os
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 

polydb/adapters/VercelKVAdapter.py

@@ -1,16 +1,17 @@
 # src/polydb/adapters/VercelKVAdapter.py
 
-import os
 import json
-import redis
+import os
 from typing import Any, Dict, List, Optional, Tuple
 
+import redis
+
+from ..base.NoSQLKVAdapter import NoSQLKVAdapter
+from ..errors import DatabaseError, NoSQLError
 from ..json_safe import json_safe
-from ..errors import NoSQLError, DatabaseError
+from ..models import PartitionConfig
 from ..retry import retry
 from ..types import JsonDict
-from ..models import PartitionConfig
-from ..base.NoSQLKVAdapter import NoSQLKVAdapter
 
 
 class VercelKVAdapter(NoSQLKVAdapter):

polydb/adapters/VercelQueueAdapter.py

@@ -1,17 +1,31 @@
-import os
 import json
-import requests
+import os
+from typing import Any, Dict, List, Optional
+
 import redis
-from typing import Dict, Any, List, Optional
+import requests
 
 from ..base.QueueAdapter import QueueAdapter
 from ..errors import QueueError
 from ..retry import retry
 
 
-class VercelQueueAdapter:
+class VercelQueueAdapter(QueueAdapter):
+    """Every sibling queue adapter (SQS/Azure/RabbitMQ) extends the real
+    QueueAdapter(ABC) contract -- this one didn't (a real, found-while-
+    adding-CI-lint drift, not a deliberate design choice: `send`/
+    `receive`/`delete` below already satisfy every abstract method the
+    base requires). Without it, `nack`/`purge`/`declare`/`status`/
+    `extend`/`delay`/`cancel` fell through to a plain AttributeError
+    instead of the base's own intentional, well-named
+    NotImplementedError('VercelQueueAdapter does not implement ...') --
+    and this class silently opted out of `isinstance(adapter,
+    QueueAdapter)` checks. `super().__init__()` is a no-op beyond setting
+    `self.logger` (unused here today, same as every other adapter's own
+    inherited logger until something actually calls it)."""
 
     def __init__(self, url: str = "", token: str = ""):
+        super().__init__()
         self.url = url or os.getenv("KV_REST_API_URL")
         self.token = token or os.getenv("KV_REST_API_TOKEN")
 

polydb/advanced_query.py

@@ -2,13 +2,14 @@
 """
 Advanced query capabilities: JOIN, subqueries, aggregates
 """
-from typing import List, Optional, Any, Dict
+
+import re
 from dataclasses import dataclass, field
 from enum import Enum
-import re
+from typing import Any, Dict, List, Optional
 
 from .errors import ValidationError
-from .utils import validate_table_name, validate_column_name
+from .utils import validate_column_name, validate_table_name
 
 # table.column / alias.column - each half validated with the same allowlists
 # used elsewhere for identifiers, joined by a single literal dot.
@@ -155,7 +156,7 @@ class AdvancedQueryBuilder:
                 select_parts = list(self.group_by_fields) + select_parts
             sql = f"SELECT {', '.join(select_parts)}"
         else:
-            sql = f"SELECT *"
+            sql = "SELECT *"
 
         # FROM clause
         sql += f" FROM {self.table}"

polydb/aio.py

@@ -0,0 +1,198 @@
+# Async API for PolyDB -- closes CLAUDE.md's own known-gap #5 ("No async
+# API. Everything is synchronous... A documented stance would at least
+# set expectations").
+#
+# THE STANCE, stated plainly: PolyDB's entire adapter layer is built on
+# genuinely synchronous SDKs -- psycopg2 (not asyncpg), boto3 (not
+# aioboto3), the sync azure-* / google-cloud-* clients, pymongo (not
+# motor), pika, kafka-python. A "real" native-async rewrite would mean
+# swapping every one of those for an async-native equivalent across every
+# adapter in `adapters/*.py` -- a from-scratch, parallel adapter layer
+# roughly doubling this package's own maintenance surface (every fix,
+# every new provider feature, landing twice), for a benefit (not blocking
+# the event loop) that a MUCH smaller, purely additive wrapper already
+# delivers for the overwhelming majority of real callers: an
+# asyncio/FastAPI app that doesn't want a slow Postgres/S3/DynamoDB call
+# to stall its event loop.
+#
+# So this module is that smaller thing, not a rewrite: `AsyncPolyDB`/
+# `AsyncDatabaseFactory` wrap the real, unchanged, synchronous
+# `PolyDB`/`DatabaseFactory` instance and run every one of its methods in
+# a worker thread via `asyncio.to_thread` (or a dedicated
+# `ThreadPoolExecutor` when `max_workers` is given), returning an
+# awaitable. This is the same "wrap a blocking DB-API driver in a thread
+# pool" pattern `encode/databases` and Starlette's own docs recommend for
+# exactly this situation -- not a novel trick, the standard one.
+#
+# Genuinely additive: `PolyDB`/`DatabaseFactory` themselves are completely
+# untouched by this module -- every existing synchronous caller keeps
+# working byte-for-byte unchanged. A caller who needs real native async
+# (avoiding thread-pool overhead entirely, or wanting async cancellation
+# semantics psycopg2 can't give) still needs the from-scratch rewrite
+# described above -- that is real, separate, much larger future work,
+# not something this module pretends to already be.
+from __future__ import annotations
+
+import asyncio
+import functools
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable, Generic, Optional, TypeVar
+
+_T = TypeVar("_T")
+
+
+class _AsyncProxy(Generic[_T]):
+    """Wraps any synchronous object `sync` and exposes every one of its
+    public callables as an `async def`-equivalent (an async function
+    returned from `__getattr__`, run via `asyncio.to_thread`/a dedicated
+    executor); every non-callable attribute passes through unchanged,
+    read synchronously (cheap, in-memory access -- never worth a thread
+    hop). Not specific to PolyDB/DatabaseFactory -- either concrete
+    subclass below just fixes the wrapped type for clearer type hints
+    and a more specific `__repr__`.
+
+    `max_workers=None` (the default) runs every call via
+    `asyncio.to_thread`, i.e. the running loop's own default executor --
+    shared with anything else in the same process already using
+    `asyncio.to_thread`, the same default a plain asyncio app already
+    has. Pass `max_workers=N` for a DEDICATED thread pool sized for this
+    instance's own expected DB/cloud-call concurrency, decoupled from
+    whatever else the host application runs on the default executor --
+    worth doing once real concurrent load is a concern, since the
+    default executor is sized `min(32, os.cpu_count() + 4)` by Python
+    itself, which can bottleneck a database-heavy workload sharing it
+    with other blocking work.
+    """
+
+    def __init__(self, sync: _T, *, max_workers: Optional[int] = None) -> None:
+        self._sync = sync
+        self._executor: Optional[ThreadPoolExecutor] = (
+            ThreadPoolExecutor(
+                max_workers=max_workers, thread_name_prefix=f"{type(self).__name__.lower()}"
+            )
+            if max_workers is not None
+            else None
+        )
+        self._wrapper_cache: dict[str, Callable[..., Any]] = {}
+
+    @property
+    def sync(self) -> _T:
+        """Escape hatch to the real, wrapped, synchronous instance -- for
+        anything this wrapper doesn't cover, or to call something
+        deliberately on the current thread (already running inside a
+        worker thread, a one-off script with no running event loop,
+        etc.)."""
+        return self._sync
+
+    async def _run(self, fn: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
+        bound = functools.partial(fn, *args, **kwargs)
+        if self._executor is not None:
+            loop = asyncio.get_running_loop()
+            return await loop.run_in_executor(self._executor, bound)
+        return await asyncio.to_thread(bound)
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        cached = self._wrapper_cache.get(name)
+        if cached is not None:
+            return cached
+        attr = getattr(self._sync, name)
+        if not callable(attr):
+            return attr
+
+        async def _async_call(*args: Any, __attr: Callable[..., Any] = attr, **kwargs: Any) -> Any:
+            return await self._run(__attr, *args, **kwargs)
+
+        _async_call.__name__ = name
+        _async_call.__doc__ = getattr(attr, "__doc__", None)
+        self._wrapper_cache[name] = _async_call
+        return _async_call
+
+    def __dir__(self) -> list[str]:
+        return sorted(set(super().__dir__()) | set(dir(self._sync)))
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self._sync!r})"
+
+    def close(self) -> None:
+        """Shuts down the dedicated executor, if one was created
+        (`max_workers` was given). A no-op when running off the shared
+        default executor (`max_workers=None`) -- there is nothing this
+        instance owns to shut down in that case."""
+        if self._executor is not None:
+            self._executor.shutdown(wait=True)
+
+    async def __aenter__(self) -> "_AsyncProxy[_T]":
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        self.close()
+
+
+class AsyncDatabaseFactory(
+    _AsyncProxy["DatabaseFactory"]
+):  # noqa: F821 -- DatabaseFactory imported lazily below for typing only
+    """Async wrapper over `DatabaseFactory` -- for callers using the
+    lower-level factory directly rather than the `PolyDB` facade. See
+    this module's own top comment for the full design rationale."""
+
+    def __init__(
+        self,
+        *args: Any,
+        max_workers: Optional[int] = None,
+        sync: Optional[Any] = None,
+        **kwargs: Any,
+    ) -> None:
+        if sync is None:
+            from .databaseFactory import DatabaseFactory
+
+            sync = DatabaseFactory(*args, **kwargs)
+        elif args or kwargs:
+            raise TypeError(
+                "AsyncDatabaseFactory: pass either `sync=<existing DatabaseFactory>` or constructor args, not both"
+            )
+        super().__init__(sync, max_workers=max_workers)
+
+
+class AsyncPolyDB(
+    _AsyncProxy["PolyDB"]
+):  # noqa: F821 -- PolyDB imported lazily below for typing only
+    """Async wrapper over the `PolyDB` facade -- the primary
+    developer-facing async entrypoint. See this module's own top comment
+    for the full design rationale (why this is a thread-pool wrapper, not
+    a native-async rewrite, and what a real native-async story would
+    require).
+
+    Usage::
+
+        db = AsyncPolyDB(provider=CloudProvider.POSTGRESQL)
+        row = await db.create(MyModel, {"id": "1", "name": "hi"})
+        rows = await db.read(MyModel, {"name": "hi"})
+
+        # or, for a dedicated thread pool sized for this instance:
+        db = AsyncPolyDB(provider=CloudProvider.POSTGRESQL, max_workers=20)
+
+        # or, wrapping an already-constructed sync PolyDB:
+        db = AsyncPolyDB(sync=existing_polydb_instance)
+
+        async with db:
+            ...  # db.close() runs automatically on exit
+    """
+
+    def __init__(
+        self,
+        *args: Any,
+        max_workers: Optional[int] = None,
+        sync: Optional[Any] = None,
+        **kwargs: Any,
+    ) -> None:
+        if sync is None:
+            from .PolyDB import PolyDB
+
+            sync = PolyDB(*args, **kwargs)
+        elif args or kwargs:
+            raise TypeError(
+                "AsyncPolyDB: pass either `sync=<existing PolyDB>` or constructor args, not both"
+            )
+        super().__init__(sync, max_workers=max_workers)

polydb/audit/AuditStorage.py

@@ -4,10 +4,10 @@ from __future__ import annotations
 import hmac
 import threading
 from dataclasses import dataclass
-from typing import Optional, Dict, Any
+from typing import Optional
 
-from .models import AuditRecord
 from ..cloudDatabaseFactory import CloudDatabaseFactory
+from .models import AuditRecord
 
 
 class AuditStorage:
@@ -54,14 +54,14 @@ class AuditStorage:
                 CONSTRAINT uq_audit_chain UNIQUE (tenant_id, previous_hash),
                 created_at TIMESTAMP DEFAULT NOW()
             );
-            
-            CREATE INDEX IF NOT EXISTS idx_audit_tenant_timestamp 
+
+            CREATE INDEX IF NOT EXISTS idx_audit_tenant_timestamp
                 ON polydb_audit_log(tenant_id, timestamp DESC);
-            CREATE INDEX IF NOT EXISTS idx_audit_model_entity 
+            CREATE INDEX IF NOT EXISTS idx_audit_model_entity
                 ON polydb_audit_log(model, entity_id);
-            CREATE INDEX IF NOT EXISTS idx_audit_actor 
+            CREATE INDEX IF NOT EXISTS idx_audit_actor
                 ON polydb_audit_log(actor_id, timestamp DESC);
-            CREATE INDEX IF NOT EXISTS idx_audit_hash_chain 
+            CREATE INDEX IF NOT EXISTS idx_audit_hash_chain
                 ON polydb_audit_log(tenant_id, timestamp DESC, previous_hash);
             """
 
@@ -74,7 +74,7 @@ class AuditStorage:
         """Get most recent hash with strict ordering (distributed-safe)"""
         with self._lock:
             try:
-                from ..query import QueryBuilder, Operator
+                from ..query import Operator, QueryBuilder
 
                 builder = QueryBuilder()
 
@@ -99,9 +99,10 @@ class AuditStorage:
         and re-chains instead of forking. (threading.Lock alone was only
         process-local — the old "distributed-safe" claim was false.)"""
         from dataclasses import asdict
+
         from .models import (
-            AuditKeyMissingError,
             AUDIT_HMAC_KEY_ENV,
+            AuditKeyMissingError,
             audit_hmac_key,
             compute_audit_hash,
             require_hmac,
@@ -157,9 +158,7 @@ class AuditStorage:
         """Verify BOTH chain linkage AND per-record content integrity."""
         return self.verify_chain_detailed(tenant_id).ok
 
-    def verify_chain_detailed(
-        self, tenant_id: Optional[str] = None
-    ) -> "ChainVerification":
+    def verify_chain_detailed(self, tenant_id: Optional[str] = None) -> "ChainVerification":
         """Verify the chain, reporting *why* rather than only whether.
 
         Two things are checked per record: that it links to its predecessor,
@@ -184,7 +183,7 @@ class AuditStorage:
         as everything after it. ``legacy_records`` reports how much of the
         chain is still resting on that seal.
         """
-        from ..query import QueryBuilder, Operator
+        from ..query import Operator, QueryBuilder
         from .models import audit_hmac_key, compute_audit_hash
 
         builder = QueryBuilder()
@@ -215,13 +214,9 @@ class AuditStorage:
 
             stored = r.get("hash") or ""
 
-            if key is not None and hmac.compare_digest(
-                stored, compute_audit_hash(r, key=key)
-            ):
+            if key is not None and hmac.compare_digest(stored, compute_audit_hash(r, key=key)):
                 seen_keyed = True
-            elif not seen_keyed and hmac.compare_digest(
-                stored, compute_audit_hash(r, key=None)
-            ):
+            elif not seen_keyed and hmac.compare_digest(stored, compute_audit_hash(r, key=None)):
                 # Predates the key. Sealed by the first keyed record that
                 # follows it, so it is only trusted while none has appeared.
                 legacy += 1

polydb/audit/__init__.py

@@ -1,7 +1,7 @@
 # src/polydb/audit/__init__.py
-from .models import AuditRecord
+from .AuditStorage import AuditStorage
 from .context import AuditContext
 from .manager import AuditManager
-from .AuditStorage import AuditStorage
+from .models import AuditRecord
 
 __all__ = ["AuditRecord", "AuditContext", "AuditManager", "AuditStorage"]

polydb/audit/context.py

@@ -1,10 +1,11 @@
 # src/polydb/audit/AuditContext.py
 from contextvars import ContextVar
-from typing import Optional, List
+from typing import List, Optional
+
 
 class AuditContext:
     """Context variables for audit trail"""
-    
+
     actor_id: ContextVar[Optional[str]] = ContextVar("actor_id", default=None)
     roles: ContextVar[List[str]] = ContextVar("roles", default=[])
     tenant_id: ContextVar[Optional[str]] = ContextVar("tenant_id", default=None)
@@ -12,7 +13,7 @@ class AuditContext:
     request_id: ContextVar[Optional[str]] = ContextVar("request_id", default=None)
     ip_address: ContextVar[Optional[str]] = ContextVar("ip_address", default=None)
     user_agent: ContextVar[Optional[str]] = ContextVar("user_agent", default=None)
-    
+
     @classmethod
     def set(
         cls,
@@ -40,7 +41,7 @@ class AuditContext:
             cls.ip_address.set(ip_address)
         if user_agent is not None:
             cls.user_agent.set(user_agent)
-    
+
     @classmethod
     def clear(cls):
         """Clear all context variables"""
@@ -50,4 +51,4 @@ class AuditContext:
         cls.trace_id.set(None)
         cls.request_id.set(None)
         cls.ip_address.set(None)
-        cls.user_agent.set(None)
+        cls.user_agent.set(None)

polydb/audit/manager.py

@@ -1,11 +1,11 @@
 # src/polydb/audit/manager.py
 from __future__ import annotations
 
-from typing import Optional, Dict, Any, List
+from typing import Any, Dict, List, Optional
 
-from .models import AuditRecord
 from .AuditStorage import AuditStorage
 from .context import AuditContext
+from .models import AuditRecord
 
 
 class AuditManager:
@@ -24,7 +24,7 @@ class AuditManager:
         before: Optional[Dict[str, Any]],
         after: Optional[Dict[str, Any]],
         error: Optional[str],
-        changed_fields: List[str] | None
+        changed_fields: List[str] | None,
     ) -> None:
         tenant_id = AuditContext.tenant_id.get()
         previous_hash = self.storage.get_last_hash(tenant_id)

polydb/audit/models.py

@@ -18,15 +18,16 @@ Records written before a key was configured stay verifiable. See
 than a loophole.
 """
 
-from dataclasses import dataclass, asdict
-from typing import Any, Dict, List, Optional
 import hashlib
 import hmac
 import json
 import logging
 import os
 import uuid
+from dataclasses import asdict, dataclass
 from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
 from ..json_safe import json_safe
 
 logger = logging.getLogger("polydb.audit")

polydb/base/NoSQLKVAdapter.py

@@ -5,14 +5,12 @@ import base64
 import hashlib
 import json
 import threading
-from typing import Any, Dict, List, Optional, Tuple, Union, TYPE_CHECKING, cast
-
-
-from ..json_safe import json_safe
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union, cast
 
 from ..errors import NoSQLError, StorageError
+from ..json_safe import json_safe
+from ..query import Operator, QueryBuilder
 from ..retry import retry
-from ..query import QueryBuilder, Operator
 from ..types import JsonDict, Lookup
 
 if TYPE_CHECKING:
@@ -234,7 +232,8 @@ class NoSQLKVAdapter:
     # Protocol implementation
     def put(self, model: type, data: JsonDict) -> JsonDict:
         pk, rk = self._get_pk_rk(model, data)
-        return self._put_raw(model, pk, rk, data)
+        store_data, _ = self._check_overflow(data)
+        return self._put_raw(model, pk, rk, store_data)
 
     def query(
         self,
@@ -340,8 +339,11 @@ class NoSQLKVAdapter:
     # ---------------------------------------------------------------
 
     @property
-    def capabilities(self) -> "BackendCapabilities":
+    def capabilities(
+        self,
+    ) -> "BackendCapabilities":  # noqa: F821 -- lazily imported below, quoted on purpose
         from ..models import BackendCapabilities
+
         return BackendCapabilities()
 
     def _encode_cursor(self, data: dict) -> str:
@@ -353,7 +355,11 @@ class NoSQLKVAdapter:
         except Exception:
             return {}
 
-    def query_paged(self, model: type, request: "PageRequest") -> "PageResult":
+    def query_paged(
+        self,
+        model: type,
+        request: "PageRequest",  # noqa: F821 -- lazily imported below, quoted on purpose
+    ) -> "PageResult":  # noqa: F821 -- lazily imported below, quoted on purpose
         """In-memory pagination with opaque offset cursor. Subclasses may override."""
         from ..models import PageResult
 
@@ -378,14 +384,16 @@ class NoSQLKVAdapter:
 
         has_more = len(results) > request.limit
         if has_more:
-            results = results[:request.limit]
+            results = results[: request.limit]
 
         next_cursor = None
         if has_more:
-            next_cursor = self._encode_cursor({
-                "offset": offset + request.limit,
-                "order_by": request.order_by,
-                "desc": request.order_desc,
-            })
+            next_cursor = self._encode_cursor(
+                {
+                    "offset": offset + request.limit,
+                    "order_by": request.order_by,
+                    "desc": request.order_desc,
+                }
+            )
 
         return PageResult(items=results, next_cursor=next_cursor, has_more=has_more)

polydb/base/ObjectStorageAdapter.py

@@ -1,8 +1,9 @@
-from ..errors import StorageError
-from ..utils import setup_logger
 from abc import ABC, abstractmethod
 from typing import Any, Dict, List, Optional
 
+from ..errors import StorageError
+from ..utils import setup_logger
+
 
 class ObjectStorageAdapter(ABC):
     """Base class for Object Storage with automatic optimization"""

polydb/base/QueueAdapter.py

@@ -1,9 +1,8 @@
-from polydb.utils import setup_logger
-
-
 from abc import ABC, abstractmethod
 from typing import Any, Dict, List, Optional
 
+from polydb.utils import setup_logger
+
 
 class QueueAdapter(ABC):
     """Base class for Queue/Message services"""

polydb/base/SecretsAdapter.py

@@ -1,7 +1,8 @@
-from ..utils import setup_logger
 from abc import ABC, abstractmethod
 from typing import Optional
 
+from ..utils import setup_logger
+
 
 class SecretsAdapter(ABC):
     """Base class for cloud secret managers (Key Vault / Secrets Manager /

polydb/base/SharedFilesAdapter.py

@@ -1,9 +1,8 @@
-from polydb.utils import setup_logger
-
-
 from abc import ABC, abstractmethod
 from typing import List, Optional
 
+from polydb.utils import setup_logger
+
 
 class SharedFilesAdapter(ABC):
     """Base class for Shared File Storage"""