alt-python-pynosqlc-core 1.0.4__py3-none-any.whl

alt_python_pynosqlc_core-1.0.4.dist-info/METADATA

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: alt-python-pynosqlc-core
+Version: 1.0.4
+Summary: Core abstraction hierarchy for pynosqlc — Driver, DriverManager, Client, Collection, Cursor, Filter, FieldCondition, UnsupportedOperationError, compliance suite
+Project-URL: Homepage, https://github.com/alt-python/pynosqlc
+Project-URL: Repository, https://github.com/alt-python/pynosqlc
+Project-URL: Documentation, https://github.com/alt-python/pynosqlc#getting-started
+Project-URL: Bug Tracker, https://github.com/alt-python/pynosqlc/issues
+Author: Craig Parravicini, Claude (Anthropic)
+License: MIT
+Keywords: async,database,driver,nosql
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# pynosqlc-core
+
+Core abstraction hierarchy for pynosqlc — a JDBC-inspired unified async NoSQL access layer for Python.
+
+Provides `DriverManager`, `Driver`, `Client`, `Collection`, `Cursor`, `Filter`, `FieldCondition`, `UnsupportedOperationError`, and a portable driver compliance suite.

alt_python_pynosqlc_core-1.0.4.dist-info/RECORD

@@ -0,0 +1,14 @@
+pynosqlc/core/__init__.py,sha256=lvHNYFoztmC1jmZo2CEeVTsoAYlW3LXISjj-cPwGQBg,1375
+pynosqlc/core/client.py,sha256=_lvuY4r8pHPCtY27rbLPQbhtMEODxc_XoBp5aO869bw,3873
+pynosqlc/core/collection.py,sha256=zj1YncYG1no3YEKAgG_oxVSP5Vb1F3Bf19W77u7mJCE,3915
+pynosqlc/core/cursor.py,sha256=GFLHnheZq-SHZFaDQW5pvfWzfEGz3VfagoTJjQoEhdY,2979
+pynosqlc/core/driver.py,sha256=VqpgbbREuMyr4TI2o4KHgPXhirjBu2Yw0qzs6pHwPT0,1174
+pynosqlc/core/driver_manager.py,sha256=tLYd67kqjSIFH294Suhoh4YeONjEqgMfEhod31GsWR0,2013
+pynosqlc/core/errors.py,sha256=yhgJACWHfhoTgQXXT6V0IIZKkkjw-xPPVV5ElpE8upU,297
+pynosqlc/core/filter.py,sha256=I3ZL0KgpSki20L5eP7xZAocEL5Y7a6FA_k5gl1zMzyo,6152
+pynosqlc/core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pynosqlc/core/testing/__init__.py,sha256=SVOhsktVPobQUTAmLEwslT_sQ2kk6KrALFMhZhop-5M,249
+pynosqlc/core/testing/compliance.py,sha256=WDrcLEstdnG3Tot2aaoI_8-luWEDEncfXLEkPK9foVM,11894
+alt_python_pynosqlc_core-1.0.4.dist-info/METADATA,sha256=3YX6BctKi9VZkoqXNXiJIJ7YJEWJSQD4ehtFxmI8jkU,1387
+alt_python_pynosqlc_core-1.0.4.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+alt_python_pynosqlc_core-1.0.4.dist-info/RECORD,,

alt_python_pynosqlc_core-1.0.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pynosqlc/core/__init__.py

@@ -0,0 +1,39 @@
+"""
+pynosqlc.core — Core abstraction hierarchy for pynosqlc.
+
+Provides:
+  Driver                 — ABC for NoSQL drivers
+  DriverManager          — Registry and URL-based connection dispatcher
+  Client                 — ABC for database clients (async context manager)
+  ClientDataSource       — Connection factory wrapping DriverManager
+  Collection             — ABC for collections / tables / buckets
+  Cursor                 — Cursor-based and bulk document access (async iterable)
+  Filter                 — Chainable query filter builder
+  FieldCondition         — Field-level condition within a Filter
+  UnsupportedOperationError — Raised when a driver does not implement an operation
+"""
+
+from __future__ import annotations
+
+from pynosqlc.core.errors import UnsupportedOperationError
+from pynosqlc.core.driver import Driver
+from pynosqlc.core.driver_manager import DriverManager
+from pynosqlc.core.cursor import Cursor
+from pynosqlc.core.collection import Collection
+from pynosqlc.core.client import Client, ClientDataSource
+from pynosqlc.core.filter import Filter, FieldCondition
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+__all__ = [
+    "Driver",
+    "DriverManager",
+    "Client",
+    "ClientDataSource",
+    "Collection",
+    "Cursor",
+    "Filter",
+    "FieldCondition",
+    "UnsupportedOperationError",
+]

pynosqlc/core/client.py

@@ -0,0 +1,112 @@
+"""
+client.py — Abstract base class for a pynosqlc client session.
+
+Drivers override ``_get_collection()`` and ``_close()``.
+Manages a cache of Collection instances keyed by name.
+Implements the async context manager protocol (``async with``).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from pynosqlc.core.driver_manager import DriverManager
+
+if TYPE_CHECKING:
+    from pynosqlc.core.collection import Collection
+
+
+class Client(ABC):
+    """A session to a NoSQL database.
+
+    Args:
+        config: optional dict; recognises key ``'url'``.
+    """
+
+    def __init__(self, config: dict | None = None) -> None:
+        cfg = config or {}
+        self._url: str | None = cfg.get("url")
+        self._closed: bool = False
+        self._collections: dict[str, "Collection"] = {}
+
+    # ── Async context manager ──────────────────────────────────────────────
+
+    async def __aenter__(self) -> "Client":
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.close()
+
+    # ── Public API ─────────────────────────────────────────────────────────
+
+    def get_collection(self, name: str) -> "Collection":
+        """Return a (cached) Collection by name.
+
+        Raises:
+            RuntimeError: if the client is closed
+        """
+        self._check_closed()
+        if name not in self._collections:
+            self._collections[name] = self._get_collection(name)
+        return self._collections[name]
+
+    async def close(self) -> None:
+        """Close the client and release all resources."""
+        self._closed = True
+        self._collections.clear()
+        await self._close()
+
+    def is_closed(self) -> bool:
+        """Return ``True`` if the client has been closed."""
+        return self._closed
+
+    def get_url(self) -> str | None:
+        """Return the pynosqlc URL this client was opened with."""
+        return self._url
+
+    # ── Abstract implementation hooks ──────────────────────────────────────
+
+    @abstractmethod
+    def _get_collection(self, name: str) -> "Collection":
+        """Create and return a new Collection instance for *name*."""
+
+    async def _close(self) -> None:
+        """Override to release driver-specific resources on close."""
+
+    # ── Internal helpers ───────────────────────────────────────────────────
+
+    def _check_closed(self) -> None:
+        if self._closed:
+            raise RuntimeError("Client is closed")
+
+
+class ClientDataSource:
+    """Convenience factory that wraps :meth:`DriverManager.get_client`.
+
+    Mirrors pydbc's DataSource pattern.
+
+    Args:
+        config: dict with keys:
+            - ``url`` (required) — pynosqlc URL
+            - ``username`` (optional)
+            - ``password`` (optional)
+            - ``properties`` (optional) — additional driver-specific options
+    """
+
+    def __init__(self, config: dict | None = None) -> None:
+        cfg = config or {}
+        self._url: str = cfg["url"]
+        self._properties: dict = {
+            "username": cfg.get("username"),
+            "password": cfg.get("password"),
+            **(cfg.get("properties") or {}),
+        }
+
+    async def get_client(self) -> Client:
+        """Return a client from the configured data source."""
+        return await DriverManager.get_client(self._url, self._properties)
+
+    def get_url(self) -> str:
+        """Return the configured pynosqlc URL."""
+        return self._url

pynosqlc/core/collection.py

@@ -0,0 +1,109 @@
+"""
+collection.py — Abstract base class for a named collection (table/bucket).
+
+Driver implementations override the ``_`` methods. All base ``_`` methods
+raise ``UnsupportedOperationError`` — drivers implement only what their
+backend supports.
+
+Operations
+----------
+Key-value : get(key), store(key, doc), delete(key)
+Document  : insert(doc), update(key, patch)
+Query     : find(ast)
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from pynosqlc.core.errors import UnsupportedOperationError
+
+if TYPE_CHECKING:
+    from pynosqlc.core.client import Client
+    from pynosqlc.core.cursor import Cursor
+
+
+class Collection(ABC):
+    """Represents a named collection within a :class:`Client`."""
+
+    def __init__(self, client: "Client", name: str) -> None:
+        self._client = client
+        self._name = name
+        self._closed: bool = False
+
+    def get_name(self) -> str:
+        """Return the collection name."""
+        return self._name
+
+    # ── Public API ─────────────────────────────────────────────────────────
+
+    async def get(self, key: str) -> dict | None:
+        """Retrieve a document by its primary key.
+
+        Returns:
+            The document dict, or ``None`` if the key does not exist.
+        """
+        self._check_closed()
+        return await self._get(key)
+
+    async def store(self, key: str, doc: dict) -> None:
+        """Store (upsert) a document under *key*."""
+        self._check_closed()
+        await self._store(key, doc)
+
+    async def delete(self, key: str) -> None:
+        """Delete the document at *key*.  No-op if the key does not exist."""
+        self._check_closed()
+        await self._delete(key)
+
+    async def insert(self, doc: dict) -> str:
+        """Insert a document and return the backend-assigned key / ``_id``."""
+        self._check_closed()
+        return await self._insert(doc)
+
+    async def update(self, key: str, patch: dict) -> None:
+        """Patch the document at *key*.
+
+        Only provided fields are updated; others are preserved (shallow merge).
+        """
+        self._check_closed()
+        await self._update(key, patch)
+
+    async def find(self, ast: dict) -> "Cursor":
+        """Find documents matching the given filter AST.
+
+        Args:
+            ast: a built filter AST from ``Filter.build()``
+
+        Returns:
+            A :class:`~pynosqlc.core.Cursor` over matching documents.
+        """
+        self._check_closed()
+        return await self._find(ast)
+
+    # ── Abstract implementation hooks ──────────────────────────────────────
+
+    async def _get(self, key: str) -> dict | None:
+        raise UnsupportedOperationError("get() is not supported by this driver")
+
+    async def _store(self, key: str, doc: dict) -> None:
+        raise UnsupportedOperationError("store() is not supported by this driver")
+
+    async def _delete(self, key: str) -> None:
+        raise UnsupportedOperationError("delete() is not supported by this driver")
+
+    async def _insert(self, doc: dict) -> str:
+        raise UnsupportedOperationError("insert() is not supported by this driver")
+
+    async def _update(self, key: str, patch: dict) -> None:
+        raise UnsupportedOperationError("update() is not supported by this driver")
+
+    async def _find(self, ast: dict) -> "Cursor":
+        raise UnsupportedOperationError("find() is not supported by this driver")
+
+    # ── Internal helpers ───────────────────────────────────────────────────
+
+    def _check_closed(self) -> None:
+        if self._closed:
+            raise RuntimeError("Collection is closed")

pynosqlc/core/cursor.py

@@ -0,0 +1,88 @@
+"""
+cursor.py — Cursor over a find() result set.
+
+Provides cursor-based iteration (next/get_document) plus bulk access
+(get_documents) and implements the async iterator protocol for use with
+``async for``.
+
+The base class buffers all results in a list. Driver implementations may
+subclass Cursor to support streaming from the database.
+"""
+
+from __future__ import annotations
+
+
+class Cursor:
+    """Async-iterable cursor over a collection of documents.
+
+    Args:
+        documents: pre-buffered result list (pass ``[]`` for an empty cursor)
+    """
+
+    def __init__(self, documents: list[dict] | None = None) -> None:
+        self._documents: list[dict] = documents if documents is not None else []
+        self._cursor: int = -1
+        self._closed: bool = False
+
+    async def next(self) -> bool:
+        """Advance to the next document.
+
+        Returns:
+            ``True`` if there is a current document; ``False`` when exhausted.
+        """
+        self._check_closed()
+        self._cursor += 1
+        return self._cursor < len(self._documents)
+
+    def get_document(self) -> dict:
+        """Return a shallow copy of the document at the current cursor position.
+
+        Raises:
+            RuntimeError: if the cursor is not on a valid document (call
+                          ``next()`` first)
+            RuntimeError: if the cursor is closed
+        """
+        self._check_closed()
+        self._check_cursor()
+        return dict(self._documents[self._cursor])
+
+    def get_documents(self) -> list[dict]:
+        """Return all documents as a list of shallow copies.
+
+        Does not require ``next()`` to have been called — returns the full
+        buffered result set.
+        """
+        self._check_closed()
+        return [dict(d) for d in self._documents]
+
+    async def close(self) -> None:
+        """Close the cursor and release resources."""
+        self._closed = True
+
+    def is_closed(self) -> bool:
+        """Return ``True`` if the cursor has been closed."""
+        return self._closed
+
+    # ── Async iterator protocol ────────────────────────────────────────────
+
+    def __aiter__(self) -> "Cursor":
+        return self
+
+    async def __anext__(self) -> dict:
+        has_more = await self.next()
+        if has_more:
+            return self.get_document()
+        await self.close()
+        raise StopAsyncIteration
+
+    # ── Internal helpers ───────────────────────────────────────────────────
+
+    def _check_closed(self) -> None:
+        if self._closed:
+            raise RuntimeError("Cursor is closed")
+
+    def _check_cursor(self) -> None:
+        if self._cursor < 0 or self._cursor >= len(self._documents):
+            raise RuntimeError(
+                "Cursor is not on a valid document — call next() first"
+            )

pynosqlc/core/driver.py

@@ -0,0 +1,41 @@
+"""
+driver.py — Abstract base class for pynosqlc drivers.
+
+Each driver implementation registers itself with DriverManager on import
+and declares which URL schemes it handles.
+
+URL scheme: pynosqlc:<subprotocol>:<connection-details>
+e.g. pynosqlc:mongodb://localhost:27017/mydb
+     pynosqlc:memory:
+     pynosqlc:dynamodb:us-east-1
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pynosqlc.core.client import Client
+
+
+class Driver(ABC):
+    """Creates client connections to a specific NoSQL database type."""
+
+    @abstractmethod
+    def accepts_url(self, url: str) -> bool:
+        """Return True if this driver handles the given pynosqlc URL.
+
+        Args:
+            url: e.g. ``'pynosqlc:mongodb://localhost:27017/mydb'``
+        """
+
+    @abstractmethod
+    async def connect(self, url: str, properties: dict | None = None) -> "Client":
+        """Create a client connection to the database.
+
+        Args:
+            url: pynosqlc URL
+            properties: optional dict with driver-specific options
+                        (e.g. username, password, endpoint)
+        """

pynosqlc/core/driver_manager.py

@@ -0,0 +1,66 @@
+"""
+driver_manager.py — Registry for pynosqlc drivers.
+
+Drivers register themselves on import. When get_client() is called,
+DriverManager iterates registered drivers to find one that accepts the URL.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pynosqlc.core.driver import Driver
+    from pynosqlc.core.client import Client
+
+
+class DriverManager:
+    """Class-level registry for pynosqlc drivers."""
+
+    _drivers: list["Driver"] = []
+
+    @classmethod
+    def register_driver(cls, driver: "Driver") -> None:
+        """Register a driver instance (idempotent — no duplicates)."""
+        if driver not in cls._drivers:
+            cls._drivers.append(driver)
+
+    @classmethod
+    def deregister_driver(cls, driver: "Driver") -> None:
+        """Remove a previously registered driver."""
+        cls._drivers = [d for d in cls._drivers if d is not driver]
+
+    @classmethod
+    async def get_client(
+        cls,
+        url: str,
+        properties: dict | None = None,
+    ) -> "Client":
+        """Return a client from the first driver that accepts *url*.
+
+        Args:
+            url: pynosqlc URL (e.g. ``'pynosqlc:memory:'``)
+            properties: optional driver-specific connection properties
+
+        Raises:
+            ValueError: if no registered driver accepts the URL
+        """
+        if properties is None:
+            properties = {}
+        for driver in cls._drivers:
+            if driver.accepts_url(url):
+                return await driver.connect(url, properties)
+        raise ValueError(
+            f"No suitable driver found for URL: {url!r}. "
+            f"Registered drivers: {[type(d).__name__ for d in cls._drivers]}"
+        )
+
+    @classmethod
+    def get_drivers(cls) -> list["Driver"]:
+        """Return a copy of the registered driver list."""
+        return list(cls._drivers)
+
+    @classmethod
+    def clear(cls) -> None:
+        """Clear all registered drivers (for testing)."""
+        cls._drivers = []

pynosqlc/core/errors.py

@@ -0,0 +1,12 @@
+"""
+errors.py — Custom exception classes for pynosqlc.
+"""
+
+from __future__ import annotations
+
+
+class UnsupportedOperationError(Exception):
+    """Raised when a driver does not implement an optional Collection operation.
+
+    Callers can ``isinstance``-check this to handle gracefully.
+    """

pynosqlc/core/filter.py

@@ -0,0 +1,176 @@
+"""
+filter.py — Chainable query filter builder and field-level condition.
+
+Usage::
+
+    ast = Filter.where('age').gt(18).and_('name').eq('Alice').build()
+    # → {'type': 'and', 'conditions': [
+    #       {'type': 'condition', 'field': 'age',  'op': 'gt', 'value': 18},
+    #       {'type': 'condition', 'field': 'name', 'op': 'eq', 'value': 'Alice'},
+    #   ]}
+
+Compound operators::
+
+    Filter.or_(filter1.build(), filter2.build())
+    # → {'type': 'or', 'conditions': [ast1, ast2]}
+
+    Filter.where('status').eq('inactive').not_()
+    # → {'type': 'not', 'condition': {'type': 'condition', ...}}
+
+AST node shapes
+---------------
+Leaf  : ``{'type': 'condition', 'field': str, 'op': str, 'value': Any}``
+And   : ``{'type': 'and',  'conditions': list[node]}``
+Or    : ``{'type': 'or',   'conditions': list[node]}``
+Not   : ``{'type': 'not',  'condition': node}``
+
+Python keyword avoidance (PEP 8 trailing underscore)
+-----------------------------------------------------
+``and()`` → ``and_()``
+``or()``  → ``or_()``  (classmethod)
+``not()`` → ``not_()``
+FieldCondition: ``in()`` → ``in_()``
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class FieldCondition:
+    """Represents a field-level condition within a :class:`Filter`.
+
+    Created by :meth:`Filter.where` or :meth:`Filter.and_`.
+    Operator methods add the condition to the owning Filter and return
+    the Filter for further chaining.
+
+    Supported operators: eq, ne, gt, gte, lt, lte, contains, in_, nin, exists
+    """
+
+    def __init__(self, field: str, filter_: "Filter") -> None:
+        self._field = field
+        self._filter = filter_
+
+    def eq(self, value: Any) -> "Filter":
+        """Equal: ``field == value``"""
+        return self._add("eq", value)
+
+    def ne(self, value: Any) -> "Filter":
+        """Not equal: ``field != value``"""
+        return self._add("ne", value)
+
+    def gt(self, value: Any) -> "Filter":
+        """Greater than: ``field > value``"""
+        return self._add("gt", value)
+
+    def gte(self, value: Any) -> "Filter":
+        """Greater than or equal: ``field >= value``"""
+        return self._add("gte", value)
+
+    def lt(self, value: Any) -> "Filter":
+        """Less than: ``field < value``"""
+        return self._add("lt", value)
+
+    def lte(self, value: Any) -> "Filter":
+        """Less than or equal: ``field <= value``"""
+        return self._add("lte", value)
+
+    def contains(self, value: Any) -> "Filter":
+        """Contains: field is a string/list that contains *value*."""
+        return self._add("contains", value)
+
+    def in_(self, values: list) -> "Filter":
+        """In: ``field`` is one of *values*."""
+        return self._add("in", values)
+
+    def nin(self, values: list) -> "Filter":
+        """Not in: ``field`` is not one of *values*."""
+        return self._add("nin", values)
+
+    def exists(self, value: bool = True) -> "Filter":
+        """Exists: field is present (True) or absent/None (False)."""
+        return self._add("exists", value)
+
+    # ── Internal ────────────────────────────────────────────────────────────
+
+    def _add(self, op: str, value: Any) -> "Filter":
+        self._filter._add_condition(
+            {"type": "condition", "field": self._field, "op": op, "value": value}
+        )
+        return self._filter
+
+
+class Filter:
+    """Chainable query filter builder.
+
+    Build a filter using the fluent API, then call :meth:`build` to produce
+    the AST dict passed to :meth:`~pynosqlc.core.Collection.find`.
+    """
+
+    def __init__(self) -> None:
+        self._conditions: list[dict] = []
+
+    @classmethod
+    def where(cls, field: str) -> FieldCondition:
+        """Start a new filter on *field*.
+
+        Returns:
+            A :class:`FieldCondition` whose operator methods return the
+            owning :class:`Filter` for further chaining.
+        """
+        f = cls()
+        return FieldCondition(field, f)
+
+    @classmethod
+    def or_(cls, *filters: "dict | Filter") -> dict:
+        """Create an OR compound of two or more AST nodes or Filter instances.
+
+        Each argument may be a built AST dict (result of ``filter.build()``)
+        or a :class:`Filter` instance (``build()`` is called automatically).
+
+        Returns:
+            ``{'type': 'or', 'conditions': [...]}``
+        """
+        conditions = [f.build() if isinstance(f, Filter) else f for f in filters]
+        return {"type": "or", "conditions": conditions}
+
+    def and_(self, field: str) -> FieldCondition:
+        """Chain an additional AND condition on a new *field*.
+
+        Returns:
+            A :class:`FieldCondition` whose operator methods return this
+            :class:`Filter` for further chaining.
+        """
+        return FieldCondition(field, self)
+
+    def not_(self) -> dict:
+        """Negate this filter.
+
+        Calls :meth:`build` internally and wraps the result in a not node.
+
+        Returns:
+            ``{'type': 'not', 'condition': <ast>}``
+        """
+        return {"type": "not", "condition": self.build()}
+
+    def build(self) -> dict:
+        """Build and return the filter AST.
+
+        - Zero conditions → ``{'type': 'and', 'conditions': []}``
+        - Single condition → the leaf node directly
+        - Multiple conditions → ``{'type': 'and', 'conditions': [...]}``
+
+        Each call returns a fresh copy — mutating the result does not affect
+        the Filter.
+        """
+        if not self._conditions:
+            return {"type": "and", "conditions": []}
+        if len(self._conditions) == 1:
+            return dict(self._conditions[0])
+        return {"type": "and", "conditions": [dict(c) for c in self._conditions]}
+
+    # ── Internal ────────────────────────────────────────────────────────────
+
+    def _add_condition(self, node: dict) -> None:
+        """Append a condition node (called by FieldCondition)."""
+        self._conditions.append(node)

pynosqlc/core/testing/__init__.py

@@ -0,0 +1,10 @@
+"""
+pynosqlc.core.testing — Shared compliance test utilities.
+
+Exports:
+    run_compliance: Register a pytest compliance suite into the calling module.
+"""
+
+from pynosqlc.core.testing.compliance import run_compliance
+
+__all__ = ["run_compliance"]

pynosqlc/core/testing/compliance.py

@@ -0,0 +1,280 @@
+"""
+compliance.py — Shared driver compliance test suite for pynosqlc drivers.
+
+Usage in a driver package's test file::
+
+    from pynosqlc.core.testing import run_compliance
+    from pynosqlc.core import DriverManager
+    import pynosqlc.memory
+
+    async def _factory():
+        DriverManager.clear()
+        import pynosqlc.memory  # re-registers the driver
+        return await DriverManager.get_client('pynosqlc:memory:')
+
+    run_compliance(_factory)
+
+``run_compliance`` uses ``sys._getframe(1).f_globals`` to inject a set of
+pytest ``Test*`` classes directly into the calling module's namespace so that
+pytest's standard discovery collects them automatically.
+
+Arguments:
+    client_factory: ``async def () -> Client`` — called before each test class
+                    to produce a fresh, open client.
+    skip_find:      if ``True``, the find-operator test class is omitted
+                    (useful for backends that do not support scan/filter).
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Callable, Coroutine
+
+import pytest
+
+from pynosqlc.core.filter import Filter
+
+
+def run_compliance(
+    client_factory: Callable[[], Coroutine[Any, Any, Any]],
+    *,
+    skip_find: bool = False,
+) -> None:
+    """Register compliance test classes into the calling module's namespace.
+
+    Pytest discovers ``Test*`` classes from module globals at collection time.
+    This function injects those classes before collection completes by writing
+    directly into ``sys._getframe(1).f_globals``.
+
+    Args:
+        client_factory: Async callable returning an open :class:`~pynosqlc.core.Client`.
+        skip_find: When ``True``, the find-operator test class is not registered.
+    """
+    caller_globals = sys._getframe(1).f_globals
+
+    # ── KV test class ──────────────────────────────────────────────────────
+
+    class TestKVCompliance:
+        """Key-value compliance: store/get, delete, upsert."""
+
+        @pytest.fixture(autouse=True)
+        async def _setup(self):
+            self.client = await client_factory()
+            self.col = self.client.get_collection("compliance_kv")
+            yield
+            if not self.client.is_closed():
+                await self.client.close()
+
+        async def test_store_and_get_retrieves_document(self):
+            await self.col.store("kv-1", {"name": "Alice", "age": 30})
+            doc = await self.col.get("kv-1")
+            assert doc is not None
+            assert doc["name"] == "Alice"
+            assert doc["age"] == 30
+
+        async def test_get_returns_none_for_missing_key(self):
+            import time
+            doc = await self.col.get(f"kv-nonexistent-{int(time.time() * 1000)}")
+            assert doc is None
+
+        async def test_store_overwrites_existing_document(self):
+            await self.col.store("kv-upsert", {"name": "Bob", "age": 25})
+            await self.col.store("kv-upsert", {"name": "Bob", "age": 26})
+            doc = await self.col.get("kv-upsert")
+            assert doc is not None
+            assert doc["age"] == 26
+
+        async def test_delete_removes_document(self):
+            await self.col.store("kv-del", {"name": "ToDelete"})
+            await self.col.delete("kv-del")
+            doc = await self.col.get("kv-del")
+            assert doc is None
+
+        async def test_delete_missing_key_does_not_raise(self):
+            import time
+            await self.col.delete(f"kv-missing-{int(time.time() * 1000)}")
+
+    # ── Document test class ────────────────────────────────────────────────
+
+    class TestDocumentCompliance:
+        """Document compliance: insert, update."""
+
+        @pytest.fixture(autouse=True)
+        async def _setup(self):
+            self.client = await client_factory()
+            self.col = self.client.get_collection("compliance_doc")
+            yield
+            if not self.client.is_closed():
+                await self.client.close()
+
+        async def test_insert_returns_an_id(self):
+            id_ = await self.col.insert({"name": "Charlie", "status": "active"})
+            assert isinstance(id_, str)
+            assert len(id_) > 0
+
+        async def test_inserted_document_retrievable_by_id(self):
+            id_ = await self.col.insert({"name": "Dana", "score": 99})
+            doc = await self.col.get(id_)
+            assert doc is not None
+            assert doc["name"] == "Dana"
+
+        async def test_two_inserts_produce_different_ids(self):
+            id1 = await self.col.insert({"name": "E1"})
+            id2 = await self.col.insert({"name": "E2"})
+            assert id1 != id2
+
+        async def test_update_patches_fields_without_destroying_others(self):
+            await self.col.store("upd-1", {"name": "Frank", "age": 40, "country": "AU"})
+            await self.col.update("upd-1", {"age": 41})
+            doc = await self.col.get("upd-1")
+            assert doc is not None
+            assert doc["age"] == 41
+            assert doc["name"] == "Frank"
+            assert doc["country"] == "AU"
+
+    # ── Lifecycle test class ───────────────────────────────────────────────
+
+    class TestLifecycleCompliance:
+        """Client lifecycle compliance."""
+
+        @pytest.fixture(autouse=True)
+        async def _setup(self):
+            self.client = await client_factory()
+            yield
+            if not self.client.is_closed():
+                await self.client.close()
+
+        def test_get_collection_returns_same_instance(self):
+            c1 = self.client.get_collection("same-name")
+            c2 = self.client.get_collection("same-name")
+            assert c1 is c2
+
+        def test_is_closed_false_for_open_client(self):
+            assert self.client.is_closed() is False
+
+    # ── Register classes into caller's module globals ──────────────────────
+
+    caller_globals["TestKVCompliance"] = TestKVCompliance
+    caller_globals["TestDocumentCompliance"] = TestDocumentCompliance
+    caller_globals["TestLifecycleCompliance"] = TestLifecycleCompliance
+
+    # ── Find test class (optional) ─────────────────────────────────────────
+
+    if skip_find:
+        return
+
+    class TestFindCompliance:
+        """Find-with-filter compliance: all operators + cursor iteration."""
+
+        # Seed data: same 5 docs as JS compliance suite
+        _SEED = [
+            ("f1", {"name": "Alice", "age": 30, "status": "active",   "tags": ["js", "ts"], "score": 85}),
+            ("f2", {"name": "Bob",   "age": 25, "status": "inactive", "tags": ["py"],        "score": 70}),
+            ("f3", {"name": "Charlie", "age": 35, "status": "active", "tags": ["js", "go"], "score": 90}),
+            ("f4", {"name": "Dana", "age": 22, "status": "pending",   "tags": ["ts"],        "score": 60}),
+            ("f5", {"name": "Eve",  "age": 30, "status": "active",    "score": 95, "email": "eve@example.com"}),
+        ]
+
+        @pytest.fixture(autouse=True)
+        async def _setup(self):
+            self.client = await client_factory()
+            self.fcol = self.client.get_collection("compliance_find")
+            for key, doc in self._SEED:
+                await self.fcol.store(key, doc)
+            yield
+            if not self.client.is_closed():
+                await self.client.close()
+
+        async def test_eq_finds_matching_documents(self):
+            cursor = await self.fcol.find(Filter.where("status").eq("active").build())
+            docs = cursor.get_documents()
+            await cursor.close()
+            assert len(docs) == 3
+            assert all(d["status"] == "active" for d in docs)
+
+        async def test_ne_finds_non_matching_documents(self):
+            cursor = await self.fcol.find(Filter.where("status").ne("active").build())
+            docs = cursor.get_documents()
+            await cursor.close()
+            assert len(docs) == 2
+            assert all(d["status"] != "active" for d in docs)
+
+        async def test_gt_finds_documents_greater_than_value(self):
+            cursor = await self.fcol.find(Filter.where("age").gt(29).build())
+            docs = cursor.get_documents()
+            await cursor.close()
+            assert len(docs) >= 2
+            assert all(d["age"] > 29 for d in docs)
+
+        async def test_lt_finds_documents_less_than_value(self):
+            cursor = await self.fcol.find(Filter.where("age").lt(25).build())
+            docs = cursor.get_documents()
+            await cursor.close()
+            assert all(d["age"] < 25 for d in docs)
+
+        async def test_gte_finds_documents_gte_value(self):
+            cursor = await self.fcol.find(Filter.where("score").gte(90).build())
+            docs = cursor.get_documents()
+            await cursor.close()
+            assert all(d["score"] >= 90 for d in docs)
+            assert len(docs) >= 2
+
+        async def test_lte_finds_documents_lte_value(self):
+            cursor = await self.fcol.find(Filter.where("score").lte(70).build())
+            docs = cursor.get_documents()
+            await cursor.close()
+            assert all(d["score"] <= 70 for d in docs)
+
+        async def test_contains_finds_array_field_contains_value(self):
+            cursor = await self.fcol.find(Filter.where("tags").contains("js").build())
+            docs = cursor.get_documents()
+            await cursor.close()
+            assert len(docs) >= 2
+            assert all("js" in d["tags"] for d in docs)
+
+        async def test_in_finds_documents_with_field_in_values(self):
+            cursor = await self.fcol.find(
+                Filter.where("status").in_(["active", "pending"]).build()
+            )
+            docs = cursor.get_documents()
+            await cursor.close()
+            assert all(d["status"] in ["active", "pending"] for d in docs)
+            assert len(docs) >= 3
+
+        async def test_nin_finds_documents_with_field_not_in_values(self):
+            cursor = await self.fcol.find(
+                Filter.where("status").nin(["inactive", "pending"]).build()
+            )
+            docs = cursor.get_documents()
+            await cursor.close()
+            assert all(d["status"] not in ["inactive", "pending"] for d in docs)
+
+        async def test_exists_true_finds_documents_where_field_present(self):
+            cursor = await self.fcol.find(Filter.where("email").exists(True).build())
+            docs = cursor.get_documents()
+            await cursor.close()
+            assert len(docs) >= 1
+            assert all(d.get("email") is not None for d in docs)
+
+        async def test_exists_false_finds_documents_where_field_absent(self):
+            cursor = await self.fcol.find(Filter.where("email").exists(False).build())
+            docs = cursor.get_documents()
+            await cursor.close()
+            assert all(d.get("email") is None for d in docs)
+
+        async def test_compound_and_applies_both_conditions(self):
+            ast = Filter.where("status").eq("active").and_("age").gt(29).build()
+            cursor = await self.fcol.find(ast)
+            docs = cursor.get_documents()
+            await cursor.close()
+            assert all(d["status"] == "active" and d["age"] > 29 for d in docs)
+            assert len(docs) >= 1
+
+        async def test_cursor_for_await_iteration(self):
+            cursor = await self.fcol.find(Filter.where("status").eq("active").build())
+            docs = []
+            async for doc in cursor:
+                docs.append(doc)
+            assert len(docs) >= 3
+
+    caller_globals["TestFindCompliance"] = TestFindCompliance