altcodepro-polydb-python 2.5.21__tar.gz → 2.5.22__tar.gz

{altcodepro_polydb_python-2.5.21/src/altcodepro_polydb_python.egg-info → altcodepro_polydb_python-2.5.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: altcodepro-polydb-python
-Version: 2.5.21
+Version: 2.5.22
 Summary: Production-ready multi-cloud database abstraction layer with connection pooling, retry logic, and thread safety
 Author: AltCodePro
 Project-URL: Homepage, https://github.com/altcodepro/polydb-python

{altcodepro_polydb_python-2.5.21 → altcodepro_polydb_python-2.5.22}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "altcodepro-polydb-python"
-version = "2.5.21"
+version = "2.5.22"
 description = "Production-ready multi-cloud database abstraction layer with connection pooling, retry logic, and thread safety"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

{altcodepro_polydb_python-2.5.21 → altcodepro_polydb_python-2.5.22/src/altcodepro_polydb_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: altcodepro-polydb-python
-Version: 2.5.21
+Version: 2.5.22
 Summary: Production-ready multi-cloud database abstraction layer with connection pooling, retry logic, and thread safety
 Author: AltCodePro
 Project-URL: Homepage, https://github.com/altcodepro/polydb-python

{altcodepro_polydb_python-2.5.21 → altcodepro_polydb_python-2.5.22}/src/altcodepro_polydb_python.egg-info/SOURCES.txt

@@ -78,6 +78,7 @@ src/polydb/base/QueueAdapter.py
 src/polydb/base/SecretsAdapter.py
 src/polydb/base/SharedFilesAdapter.py
 src/polydb/base/__init__.py
+src/polydb/base/constraints.py
 src/polydb/observability/__init__.py
 src/polydb/observability/logging.py
 src/polydb/services/__init__.py
@@ -110,6 +111,7 @@ tests/test_mongodb.py
 tests/test_monitoring_health.py
 tests/test_multi_engine.py
 tests/test_multitenancy_ddl_injection.py
+tests/test_nosql_constraints.py
 tests/test_nosql_kv_overflow_write_path.py
 tests/test_nosql_operator_injection.py
 tests/test_observability.py

{altcodepro_polydb_python-2.5.21 → altcodepro_polydb_python-2.5.22}/src/polydb/__init__.py

@@ -4,7 +4,7 @@ PolyDB - Enterprise Cloud-Independent Database Abstraction
 Full LINQ support, field-level audit, cache, soft delete, overflow storage
 """
 
-__version__ = "2.5.20"
+__version__ = "2.5.22"
 
 from .aio import AsyncDatabaseFactory, AsyncPolyDB
 from .audit.context import AuditContext

{altcodepro_polydb_python-2.5.21 → altcodepro_polydb_python-2.5.22}/src/polydb/adapters/AzureTableStorageAdapter.py

@@ -40,6 +40,10 @@ _BASE64_RE = re.compile(r"^[A-Za-z0-9+/]*={0,2}$")
 # ensures model isolation across the same table
 _MODEL_FIELD = "__polydb_model__"
 
+
+class _AlreadyExists(Exception):
+    """create_entity found the (PartitionKey, RowKey) taken. Deliberately NOT a NoSQLError so `@retry` does not retry it."""
+
 _CONNECT_TIMEOUT = float(os.getenv("AZURE_TABLE_CONNECT_TIMEOUT", "10"))
 _READ_TIMEOUT = float(os.getenv("AZURE_TABLE_READ_TIMEOUT", "30"))
 _RETRY_TOTAL = int(os.getenv("AZURE_TABLE_RETRY_TOTAL", "3"))
@@ -557,7 +561,9 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
         return restored
 
     @retry(max_attempts=3, delay=1.0, exceptions=(NoSQLError,))
-    def _put_raw(self, model: type, pk: str, rk: str, data: JsonDict) -> JsonDict:
+    def _put_raw(
+        self, model: type, pk: str, rk: str, data: JsonDict, *, _insert_only: bool = False
+    ) -> JsonDict:
         try:
             table_client = self._get_table_client(model)
             safe_pk = self._sanitize_pk_rk(pk)
@@ -632,7 +638,10 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
                 else:
                     reference_entity[k] = v
 
-            table_client.upsert_entity(reference_entity)
+            if _insert_only:
+                table_client.create_entity(reference_entity)  # 409 when the key is taken: atomic claim
+            else:
+                table_client.upsert_entity(reference_entity)
 
             restored = self._unpack_entity(model, entity)
             # Mirror the write-side condition above (line ~521): only
@@ -659,11 +668,27 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
             return restored
 
         except Exception as e:
+            if _insert_only and (
+                type(e).__name__ == "ResourceExistsError" or "EntityAlreadyExists" in str(e)
+            ):
+                raise _AlreadyExists() from e
             if "PropertyValueTooLarge" in str(e):
                 raise NoSQLError("Azure Table limit exceeded → must use blob overflow") from e
 
             raise NoSQLError(f"Azure Table put failed: {str(e)}")
 
+    def _put_new_raw(self, model: type, pk: str, rk: str, data: JsonDict) -> bool:
+        """Atomic insert-if-absent via Table Storage's `create_entity` (HTTP 409 when the key exists)."""
+        try:
+            self._put_raw(model, pk, rk, data, _insert_only=True)
+            return True
+        except _AlreadyExists:
+            return False
+
+    def _query_partition_raw(self, model: type, partition: str, limit: Optional[int]) -> List[JsonDict]:
+        """One partition -- a PartitionKey filter, not a table scan."""
+        return self._query_raw(model, {"partition_key": partition}, limit)
+
     @retry(max_attempts=3, delay=1.0, exceptions=(NoSQLError,))
     def _get_raw(self, model: type, pk: str, rk: str) -> Optional[JsonDict]:
         try:

{altcodepro_polydb_python-2.5.21 → altcodepro_polydb_python-2.5.22}/src/polydb/base/NoSQLKVAdapter.py

@@ -12,6 +12,7 @@ from ..json_safe import json_safe
 from ..query import Operator, QueryBuilder
 from ..retry import retry
 from ..types import JsonDict, Lookup
+from .constraints import NoSQLConstraintsMixin, UniqueConstraintError  # noqa: F401  (re-exported)
 
 if TYPE_CHECKING:
     from ..models import PartitionConfig
@@ -46,7 +47,7 @@ def select_columns(
     return None
 
 
-class NoSQLKVAdapter:
+class NoSQLKVAdapter(NoSQLConstraintsMixin):
     """Base with auto-overflow and LINQ support"""
 
     # An adapter sets this True when its `_query_raw` accepts `select=[property names]` and really sends it to the store (Azure
@@ -266,8 +267,16 @@ class NoSQLKVAdapter:
     # Protocol implementation
     def put(self, model: type, data: JsonDict) -> JsonDict:
         pk, rk = self._get_pk_rk(model, data)
-        store_data, _ = self._check_overflow(data)
-        return self._put_raw(model, pk, rk, store_data)
+
+        def _write() -> JsonDict:
+            store_data, _ = self._check_overflow(data)
+            return self._put_raw(model, pk, rk, store_data)
+
+        uq, ix = self._constraint_fields(model)
+        if not (uq or ix):
+            return _write()
+        previous = self._get_raw(model, pk, rk)
+        return self._constrained_write(model, pk, rk, previous, {**(previous or {}), **data}, _write)
 
     def query(
         self,
@@ -279,6 +288,9 @@ class NoSQLKVAdapter:
         fields: Optional[List[str]] = None,
         omit: Optional[List[str]] = None,
     ) -> List[JsonDict]:
+        indexed = self._indexed_query(model, query or {}, limit)
+        if indexed is not None:
+            return project_rows([self._retrieve_overflow(r) for r in indexed], fields, omit)
         select = select_columns(fields, omit, getattr(model, "__polydb__", {}).get("columns"))
         if select is not None and self.SUPPORTS_SELECT_PUSHDOWN:
             results = self._query_raw(model, query or {}, limit, select=select)
@@ -318,15 +330,25 @@ class NoSQLKVAdapter:
         else:
             pk, rk = self._get_pk_rk(model, {"id": entity_id, **data})
 
-        if not replace:
+        uq, ix = self._constraint_fields(model)
+        constrained = bool(uq or ix) and pk is not None
+        previous: Optional[JsonDict] = None
+        if not replace or constrained:
             existing = self._get_raw(model, pk, rk)  # type: ignore
             if existing:
                 existing = self._retrieve_overflow(existing)
-                existing.update(data)
-                data = existing
+                previous = dict(existing)
+                if not replace:
+                    existing.update(data)
+                    data = existing
+
+        def _write() -> JsonDict:
+            store_data, _ = self._check_overflow(data)
+            return self._put_raw(model, pk, rk, store_data)  # type: ignore
 
-        store_data, _ = self._check_overflow(data)
-        return self._put_raw(model, pk, rk, store_data)  # type: ignore
+        if not constrained:
+            return _write()
+        return self._constrained_write(model, pk, rk, previous, data, _write)  # type: ignore[arg-type]
 
     def upsert(self, model: type, data: JsonDict, *, replace: bool = False) -> JsonDict:
         return self.put(model, data)
@@ -340,7 +362,13 @@ class NoSQLKVAdapter:
         else:
             pk, rk = self._get_pk_rk(model, {"id": entity_id})
 
-        return self._delete_raw(model, pk, rk, etag)  # type: ignore
+        uq, ix = self._constraint_fields(model)
+        if not (uq or ix) or pk is None:
+            return self._delete_raw(model, pk, rk, etag)  # type: ignore
+        existing = self._get_raw(model, pk, rk)  # type: ignore
+        result = self._delete_raw(model, pk, rk, etag)  # type: ignore
+        self._release_all(model, pk, rk, existing)
+        return result
 
     def query_linq_rows(self, model: type, builder: QueryBuilder) -> List[JsonDict]:
         """

altcodepro_polydb_python-2.5.22/src/polydb/base/constraints.py

@@ -0,0 +1,260 @@
+# src/polydb/base/constraints.py
+"""
+Unique constraints and equality lookup indexes for key/value NoSQL stores.
+
+Table Storage (and every other KV backend here) enforces uniqueness only for the (PartitionKey, RowKey) pair and can only be
+queried efficiently by those two keys. A model that declares `unique_fields` / `index_fields` in `__polydb__` gets both from this
+mixin, on every NoSQL adapter, with no per-provider code beyond one primitive (`_put_new_raw`, insert-if-absent).
+
+How it works -- two hidden side tables per model (`<table>uq`, `<table>ix`):
+
+* UNIQUE   one "claim" row per (field, value): PartitionKey = u<2 hex of the hash>, RowKey = sha256(field, value). The claim is
+           written with an INSERT-IF-ABSENT before the entity, so two writers racing for one value cannot both succeed. A
+           duplicate raises UniqueConstraintError. The claim names its owner entity; a claim whose owner no longer exists, or
+           whose owner moved to another value (a crash between the claim and the entity write), is taken over.
+* INDEX    one row per (field, value, entity): PartitionKey = i<hash of (field, value)>, RowKey = hash of the entity key. An
+           equality query on an indexed field reads that one partition, then point-reads each owner and re-checks every filter,
+           so a stale index row can never produce a wrong result (it is skipped).
+
+Ordering: claims and index rows are written BEFORE the entity and removed AFTER a delete / value change, so a visible entity
+always has its rows. The residue of a crash is a stale row, which is harmless (verified on read, taken over on the next claim).
+
+Not covered: rows written before a field was declared have no claim/index row -- run `rebuild_constraints()` once. Backends
+without a native conditional insert fall back to a non-atomic get-then-put (documented on `_put_new_raw`).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+from ..errors import NoSQLError
+from ..types import JsonDict
+
+_UNSAFE_KEY = re.compile(r"[\\/#\?\x00-\x1f\x7f:+ ]")
+_UQ, _IX = "uq", "ix"
+
+
+class UniqueConstraintError(NoSQLError):
+    """A write would create a second row with a value a `unique_fields` field already holds."""
+
+    def __init__(self, field: str, value: Any):
+        super().__init__(f"unique constraint violated on {field!r}")
+        self.field = field
+        self.value = value
+
+
+def normalize_value(value: Any) -> Optional[str]:
+    """The string two values are compared as. None/empty/containers carry no constraint."""
+    if value is None or isinstance(value, (dict, list, tuple, set)):
+        return None
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    text = str(value)
+    return text if text != "" else None
+
+
+def _digest(*parts: str) -> str:
+    return hashlib.sha256("\x1f".join(parts).encode("utf-8")).hexdigest()
+
+
+class NoSQLConstraintsMixin:
+    """Mixed into NoSQLKVAdapter. Needs `_get_raw`, `_put_raw`, `_delete_raw`, `_query_raw`, `_get_pk_rk`."""
+
+    # -- metadata ---------------------------------------------------------------------------------------------------------
+
+    @staticmethod
+    def _constraint_fields(model: type) -> Tuple[Tuple[str, ...], Tuple[str, ...]]:
+        meta = getattr(model, "__polydb__", None) or {}
+        return tuple(meta.get("unique_fields") or ()), tuple(meta.get("index_fields") or ())
+
+    def _side_model(self, model: type, suffix: str) -> type:
+        cache = self.__dict__.setdefault("_side_models", {})
+        meta = getattr(model, "__polydb__", None) or {}
+        base = meta.get("collection") or meta.get("collection_name") or meta.get("table") or getattr(model, "__name__", "model")
+        base = re.sub(r"[^A-Za-z0-9]", "", str(base)).lower()[:58] or "model"
+        key = (base, suffix)
+        if key not in cache:
+            name = f"{base}{suffix}"
+            cache[key] = type(name, (), {"__polydb__": {"storage": "nosql", "table": name, "pk_field": "bucket", "rk_field": "id"}})
+        return cache[key]
+
+    # -- insert-if-absent primitive ----------------------------------------------------------------------------------------
+
+    def _put_new_raw(self, model: type, pk: str, rk: str, data: JsonDict) -> bool:
+        """Insert only when (pk, rk) is absent. True = inserted, False = already there. This default is get-then-put and is NOT
+        atomic; an adapter with a native conditional create (Azure `create_entity`, Dynamo `attribute_not_exists`, ...) overrides."""
+        if self._get_raw(model, pk, rk) is not None:  # type: ignore[attr-defined]
+            return False
+        self._put_raw(model, pk, rk, data)  # type: ignore[attr-defined]
+        return True
+
+    def _query_partition_raw(self, model: type, partition: str, limit: Optional[int]) -> List[JsonDict]:
+        """Every row of one partition. Portable default: a property equality on the mirrored `ix_bucket` field."""
+        return self._query_raw(model, {"ix_bucket": partition}, limit)  # type: ignore[attr-defined]
+
+    # -- side-row helpers --------------------------------------------------------------------------------------------------
+
+    def _safe_delete(self, model: type, pk: str, rk: str) -> None:
+        try:
+            self._delete_raw(model, pk, rk, None)  # type: ignore[attr-defined]
+        except Exception:  # already gone, or the row was never written
+            pass
+
+    def _claim(self, model: type, pk: str, rk: str, field: str, value: str) -> None:
+        side = self._side_model(model, _UQ)
+        h = _digest(field, value)
+        spk = f"u{h[:2]}"
+        row = {"bucket": spk, "ix_bucket": spk, "id": h, "field": field, "owner_pk": pk, "owner_rk": rk}
+        for _ in range(4):
+            if self._put_new_raw(side, spk, h, row):
+                return
+            cur = self._get_raw(side, spk, h)  # type: ignore[attr-defined]
+            if cur is None:  # released between our insert and our read
+                continue
+            if (cur.get("owner_pk"), cur.get("owner_rk")) == (pk, rk):
+                return  # our own claim (an idempotent retry)
+            owner = self._get_raw(model, cur.get("owner_pk"), cur.get("owner_rk"))  # type: ignore[attr-defined]
+            if owner is not None and normalize_value(owner.get(field)) == value:
+                raise UniqueConstraintError(field, value)
+            self._safe_delete(side, spk, h)  # orphaned or moved-on claim: take it over
+        raise UniqueConstraintError(field, value)
+
+    def _release(self, model: type, pk: str, rk: str, field: str, value: str) -> None:
+        side = self._side_model(model, _UQ)
+        h = _digest(field, value)
+        spk = f"u{h[:2]}"
+        cur = self._get_raw(side, spk, h)  # type: ignore[attr-defined]
+        if cur is not None and (cur.get("owner_pk"), cur.get("owner_rk")) == (pk, rk):
+            self._safe_delete(side, spk, h)
+
+    def _index_key(self, field: str, value: str, pk: str, rk: str) -> Tuple[str, str]:
+        return f"i{_digest(field, value)}", _digest(str(pk), str(rk))
+
+    def _index_put(self, model: type, pk: str, rk: str, field: str, value: str) -> None:
+        side = self._side_model(model, _IX)
+        spk, srk = self._index_key(field, value, pk, rk)
+        row = {"bucket": spk, "ix_bucket": spk, "id": srk, "field": field, "owner_pk": pk, "owner_rk": rk}
+        self._put_raw(side, spk, srk, row)  # type: ignore[attr-defined]
+
+    def _index_del(self, model: type, pk: str, rk: str, field: str, value: str) -> None:
+        spk, srk = self._index_key(field, value, pk, rk)
+        self._safe_delete(self._side_model(model, _IX), spk, srk)
+
+    # -- write path --------------------------------------------------------------------------------------------------------
+
+    def _constrained_write(self, model: type, pk: str, rk: str, previous: Optional[JsonDict], new: JsonDict, write):
+        """Claim -> index -> entity write -> release/remove the old rows. `new` is the row as it will exist afterwards."""
+        uq, ix = self._constraint_fields(model)
+        prev = previous or {}
+        claimed: List[Tuple[str, str]] = []
+        try:
+            for f in uq:
+                nv, ov = normalize_value(new.get(f)), normalize_value(prev.get(f))
+                if nv is not None and nv != ov:
+                    self._claim(model, pk, rk, f, nv)
+                    claimed.append((f, nv))
+            for f in ix:
+                nv, ov = normalize_value(new.get(f)), normalize_value(prev.get(f))
+                if nv is not None and nv != ov:
+                    self._index_put(model, pk, rk, f, nv)
+            result = write()
+        except Exception:
+            for f, v in claimed:
+                self._release(model, pk, rk, f, v)
+            raise
+        for f in uq:
+            nv, ov = normalize_value(new.get(f)), normalize_value(prev.get(f))
+            if ov is not None and ov != nv:
+                self._release(model, pk, rk, f, ov)
+        for f in ix:
+            nv, ov = normalize_value(new.get(f)), normalize_value(prev.get(f))
+            if ov is not None and ov != nv:
+                self._index_del(model, pk, rk, f, ov)
+        return result
+
+    def _release_all(self, model: type, pk: str, rk: str, row: Optional[JsonDict]) -> None:
+        if not row:
+            return
+        uq, ix = self._constraint_fields(model)
+        for f in uq:
+            v = normalize_value(row.get(f))
+            if v is not None:
+                self._release(model, pk, rk, f, v)
+        for f in ix:
+            v = normalize_value(row.get(f))
+            if v is not None:
+                self._index_del(model, pk, rk, f, v)
+
+    # -- read path ---------------------------------------------------------------------------------------------------------
+
+    def _lookup_owners(self, model: type, field: str, value: str, limit: Optional[int]) -> List[Tuple[str, str]]:
+        uq, _ = self._constraint_fields(model)
+        h = _digest(field, value)
+        if field in uq:
+            cur = self._get_raw(self._side_model(model, _UQ), f"u{h[:2]}", h)  # type: ignore[attr-defined]
+            return [(cur["owner_pk"], cur["owner_rk"])] if cur else []
+        rows = self._query_partition_raw(self._side_model(model, _IX), f"i{h}", limit)
+        return [(r["owner_pk"], r["owner_rk"]) for r in rows if r.get("owner_pk") is not None]
+
+    @staticmethod
+    def _filter_matches(row: JsonDict, query: Dict[str, Any], pk: str, rk: str) -> bool:
+        for k, want in query.items():
+            if k in ("partition_key", "PartitionKey"):
+                if _UNSAFE_KEY.sub("_", str(pk)) != str(want):
+                    return False
+            elif k in ("row_key", "RowKey"):
+                if _UNSAFE_KEY.sub("_", str(rk)) != str(want):
+                    return False
+            elif want is None:
+                if row.get(k) is not None:
+                    return False
+            elif normalize_value(row.get(k)) != normalize_value(want):
+                return False
+        return True
+
+    def _indexed_query(self, model: type, query: Dict[str, Any], limit: Optional[int]) -> Optional[List[JsonDict]]:
+        """Rows for a query that has an equality on a unique/indexed field, or None when the index cannot serve it."""
+        uq, ix = self._constraint_fields(model)
+        if not query or not (uq or ix):
+            return None
+        if any(isinstance(v, (dict, list, tuple, set)) for v in query.values()):
+            return None
+        for f in (*uq, *ix):
+            nv = normalize_value(query.get(f)) if f in query else None
+            if nv is None:
+                continue
+            out: List[JsonDict] = []
+            for opk, ork in self._lookup_owners(model, f, nv, None):
+                row = self._get_raw(model, opk, ork)  # type: ignore[attr-defined]
+                if row is not None and self._filter_matches(row, query, opk, ork):
+                    out.append(row)
+                    if limit and len(out) >= limit:
+                        break
+            return out
+        return None
+
+    def rebuild_constraints(self, model: type) -> Dict[str, int]:
+        """One-off backfill for rows written before a field was declared unique/indexed. Claims every existing value (the
+        first holder keeps it; a duplicate is reported, not overwritten) and writes every index row."""
+        uq, ix = self._constraint_fields(model)
+        done = {"rows": 0, "claims": 0, "indexed": 0, "duplicates": 0}
+        for row in self._query_raw(model, {}, None):  # type: ignore[attr-defined]
+            pk, rk = self._get_pk_rk(model, row)  # type: ignore[attr-defined]
+            done["rows"] += 1
+            for f in uq:
+                v = normalize_value(row.get(f))
+                if v is None:
+                    continue
+                try:
+                    self._claim(model, pk, rk, f, v)
+                    done["claims"] += 1
+                except UniqueConstraintError:
+                    done["duplicates"] += 1
+            for f in ix:
+                v = normalize_value(row.get(f))
+                if v is not None:
+                    self._index_put(model, pk, rk, f, v)
+                    done["indexed"] += 1
+        return done

{altcodepro_polydb_python-2.5.21 → altcodepro_polydb_python-2.5.22}/src/polydb/databaseFactory.py

@@ -167,6 +167,8 @@ def _extract_meta(model: Union[type, str]) -> ModelMeta:
                 cache=raw.get("cache", False),
                 cache_ttl=raw.get("cache_ttl"),
                 encrypted_fields=tuple(raw.get("encrypted_fields") or ()),
+                unique_fields=tuple(raw.get("unique_fields") or ()),
+                index_fields=tuple(raw.get("index_fields") or ()),
             )
     return ModelMeta(storage="nosql", table=None, collection=None)
 

{altcodepro_polydb_python-2.5.21 → altcodepro_polydb_python-2.5.22}/src/polydb/types.py

@@ -26,6 +26,9 @@ class ModelMeta:
     cache_ttl: Optional[int] = None
     # Fields stored encrypted when the factory has encryption enabled (a tuple: the dataclass is frozen/hashable).
     encrypted_fields: Tuple[str, ...] = ()
+    # NoSQL: fields that must stay unique across the model / that get an equality lookup index (see base/constraints.py).
+    unique_fields: Tuple[str, ...] = ()
+    index_fields: Tuple[str, ...] = ()
 
 
 @runtime_checkable

altcodepro_polydb_python-2.5.22/tests/test_nosql_constraints.py

@@ -0,0 +1,212 @@
+"""
+tests/test_nosql_constraints.py
+================================
+Unique constraints and equality indexes for key/value NoSQL adapters (base/constraints.py). A bare in-memory
+NoSQLKVAdapter subclass stands in for the store; the Azure `create_entity` primitive is exercised through the same
+`_put_new_raw` contract (atomic insert-if-absent).
+"""
+
+from __future__ import annotations
+
+import threading
+
+import pytest
+
+from polydb.base.NoSQLKVAdapter import NoSQLKVAdapter
+from polydb.base.constraints import UniqueConstraintError, normalize_value
+
+
+class MemKV(NoSQLKVAdapter):
+    def __init__(self):
+        super().__init__()
+        self.rows: dict[tuple, dict] = {}
+        self._mu = threading.Lock()
+        self.fail_main_write = False
+
+    @staticmethod
+    def _t(model):
+        return (getattr(model, "__polydb__", {}) or {}).get("table") or model.__name__
+
+    def _put_raw(self, model, pk, rk, data):
+        if self.fail_main_write and self._t(model) == "people":
+            raise RuntimeError("boom")
+        with self._mu:
+            self.rows[(self._t(model), str(pk), str(rk))] = dict(data)
+        return dict(data)
+
+    def _put_new_raw(self, model, pk, rk, data):  # atomic, like Azure create_entity
+        with self._mu:
+            key = (self._t(model), str(pk), str(rk))
+            if key in self.rows:
+                return False
+            self.rows[key] = dict(data)
+            return True
+
+    def _get_raw(self, model, pk, rk):
+        r = self.rows.get((self._t(model), str(pk), str(rk)))
+        return dict(r) if r is not None else None
+
+    def _query_raw(self, model, filters, limit, select=None):
+        t = self._t(model)
+        out = []
+        for (tb, pk, rk), r in self.rows.items():
+            if tb != t:
+                continue
+            if all(r.get(k) == v for k, v in (filters or {}).items()):
+                out.append(dict(r))
+        return out[:limit] if limit else out
+
+    def _delete_raw(self, model, pk, rk, etag):
+        with self._mu:
+            existed = self.rows.pop((self._t(model), str(pk), str(rk)), None)
+        if existed is None:
+            raise KeyError("missing")
+        return {"deleted": True}
+
+    def claims(self):
+        return [k for k in self.rows if k[0].endswith("uq")]
+
+    def index_rows(self):
+        return [k for k in self.rows if k[0].endswith("ix")]
+
+
+class Person:
+    __polydb__ = {"storage": "nosql", "table": "people", "pk_field": "org", "rk_field": "id",
+                  "unique_fields": ["email"], "index_fields": ["city"]}
+
+
+class Plain:
+    __polydb__ = {"storage": "nosql", "table": "plain", "pk_field": "org", "rk_field": "id"}
+
+
+@pytest.fixture
+def kv():
+    return MemKV()
+
+
+def person(i, email, city="Leeds", org="o1"):
+    return {"org": org, "id": i, "email": email, "city": city, "name": f"n{i}"}
+
+
+def test_a_duplicate_unique_value_is_rejected(kv):
+    kv.put(Person, person("1", "a@x.com"))
+    with pytest.raises(UniqueConstraintError) as e:
+        kv.put(Person, person("2", "a@x.com"))
+    assert e.value.field == "email"
+    assert kv._get_raw(Person, "o1", "2") is None  # the second row was never written
+
+
+def test_uniqueness_is_global_not_per_partition(kv):
+    kv.put(Person, person("1", "a@x.com", org="o1"))
+    with pytest.raises(UniqueConstraintError):
+        kv.put(Person, person("1", "a@x.com", org="o2"))
+
+
+def test_rewriting_the_same_row_is_idempotent(kv):
+    kv.put(Person, person("1", "a@x.com"))
+    kv.put(Person, person("1", "a@x.com", city="York"))
+    assert len(kv.claims()) == 1
+
+
+def test_changing_a_value_moves_the_claim_and_frees_the_old_value(kv):
+    kv.put(Person, person("1", "a@x.com"))
+    kv.patch(Person, {"partition_key": "o1", "id": "1"}, {"email": "b@x.com"})
+    kv.put(Person, person("2", "a@x.com"))  # the old value is free again
+    with pytest.raises(UniqueConstraintError):
+        kv.patch(Person, {"partition_key": "o1", "id": "2"}, {"email": "b@x.com"})
+    assert kv._get_raw(Person, "o1", "2")["email"] == "a@x.com"  # a rejected patch changed nothing
+
+
+def test_delete_releases_the_claim_and_index_rows(kv):
+    kv.put(Person, person("1", "a@x.com"))
+    kv.delete(Person, {"partition_key": "o1", "id": "1"})
+    assert kv.claims() == [] and kv.index_rows() == []
+    kv.put(Person, person("2", "a@x.com"))
+
+
+def test_a_failed_entity_write_releases_what_it_claimed(kv):
+    kv.fail_main_write = True
+    with pytest.raises(RuntimeError):
+        kv.put(Person, person("1", "a@x.com"))
+    kv.fail_main_write = False
+    assert kv.claims() == []
+    kv.put(Person, person("2", "a@x.com"))
+
+
+def test_an_orphaned_claim_is_taken_over(kv):
+    # a crash after the claim but before the entity write leaves a claim whose owner does not exist
+    side = kv._side_model(Person, "uq")
+    from polydb.base.constraints import _digest
+    h = _digest("email", "a@x.com")
+    kv.rows[(side.__polydb__["table"], f"u{h[:2]}", h)] = {"id": h, "owner_pk": "o1", "owner_rk": "ghost"}
+    kv.put(Person, person("1", "a@x.com"))
+    assert kv._get_raw(Person, "o1", "1")["email"] == "a@x.com"
+
+
+def test_concurrent_writers_cannot_both_take_one_value(kv):
+    results = []
+
+    def run(i):
+        try:
+            kv.put(Person, person(str(i), "race@x.com"))
+            results.append("ok")
+        except UniqueConstraintError:
+            results.append("dup")
+
+    ts = [threading.Thread(target=run, args=(i,)) for i in range(12)]
+    [t.start() for t in ts]
+    [t.join() for t in ts]
+    assert results.count("ok") == 1 and results.count("dup") == 11
+
+
+def test_equality_query_on_a_unique_field_is_a_point_read(kv):
+    kv.put(Person, person("1", "a@x.com"))
+    kv.put(Person, person("2", "b@x.com"))
+    calls = {"scan": 0}
+    real = kv._query_raw
+    kv._query_raw = lambda m, f, l, select=None: (calls.__setitem__("scan", calls["scan"] + 1), real(m, f, l))[1]
+    rows = kv.query(Person, {"email": "b@x.com"})
+    assert [r["id"] for r in rows] == ["2"] and calls["scan"] == 0
+
+
+def test_equality_query_on_an_indexed_field_uses_the_index(kv):
+    for i, c in enumerate(["Leeds", "York", "Leeds", "Leeds"]):
+        kv.put(Person, person(str(i), f"{i}@x.com", city=c))
+    rows = kv.query(Person, {"city": "Leeds"})
+    assert sorted(r["id"] for r in rows) == ["0", "2", "3"]
+    assert len(kv.query(Person, {"city": "Leeds"}, limit=2)) == 2
+    assert kv.query(Person, {"city": "Leeds", "name": "n2"})[0]["id"] == "2"  # remaining filters still apply
+    assert kv.query(Person, {"city": "Nowhere"}) == []
+
+
+def test_a_stale_index_row_never_returns_a_wrong_row(kv):
+    kv.put(Person, person("1", "a@x.com", city="Leeds"))
+    # the entity moved on but a crash left its old index row behind
+    kv.rows[(kv._t(Person), "o1", "1")]["city"] = "York"
+    assert kv.query(Person, {"city": "Leeds"}) == []
+
+
+def test_a_key_hint_in_the_query_is_honoured(kv):
+    kv.put(Person, person("1", "a@x.com", org="o1"))
+    assert kv.query(Person, {"email": "a@x.com", "partition_key": "o1"})
+    assert kv.query(Person, {"email": "a@x.com", "partition_key": "other"}) == []
+
+
+def test_models_without_constraints_are_untouched(kv):
+    kv.put(Plain, {"org": "o", "id": "1", "email": "a"})
+    kv.put(Plain, {"org": "o", "id": "2", "email": "a"})
+    assert kv.claims() == [] and kv.index_rows() == []
+    assert len(kv.query(Plain, {"email": "a"})) == 2
+
+
+def test_rebuild_backfills_rows_written_before_the_constraint_existed(kv):
+    kv.rows[("people", "o1", "1")] = person("1", "a@x.com", city="Leeds")
+    kv.rows[("people", "o1", "2")] = person("2", "a@x.com", city="Leeds")  # a legacy duplicate
+    done = kv.rebuild_constraints(Person)
+    assert done["claims"] == 1 and done["duplicates"] == 1 and done["indexed"] == 2
+    assert len(kv.query(Person, {"city": "Leeds"})) == 2
+
+
+@pytest.mark.parametrize("v,want", [(None, None), ("", None), ({"a": 1}, None), (True, "true"), (5, "5"), ("x", "x")])
+def test_normalize_value(v, want):
+    assert normalize_value(v) == want