alt-python-pynosqlc-cosmosdb 1.0.0__tar.gz

alt_python_pynosqlc_cosmosdb-1.0.0/.gitignore

@@ -0,0 +1,30 @@
+
+# ── GSD baseline (auto-generated) ──
+.gsd
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+*~
+.idea/
+.vscode/
+*.code-workspace
+.env
+.env.*
+!.env.example
+node_modules/
+.next/
+dist/
+build/
+__pycache__/
+*.pyc
+.venv/
+venv/
+target/
+vendor/
+*.log
+coverage/
+.cache/
+tmp/
+
+/.bg-shell/

alt_python_pynosqlc_cosmosdb-1.0.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: alt-python-pynosqlc-cosmosdb
+Version: 1.0.0
+Summary: CosmosDB driver for pynosqlc
+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,azure,cosmosdb,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
+Requires-Python: >=3.12
+Requires-Dist: alt-python-pynosqlc-core
+Requires-Dist: azure-cosmos>=4.7
+Description-Content-Type: text/markdown
+
+# pynosqlc-cosmosdb
+
+Azure Cosmos DB driver for [pynosqlc](https://github.com/alt-python/pynosqlc) — connects to Azure Cosmos DB (or the local emulator) via the azure-cosmos async client.
+
+## Install
+
+```
+pip install alt-python-pynosqlc-cosmosdb
+```
+
+## Requirements
+
+- Python 3.12+
+- azure-cosmos 4.7+
+- An Azure Cosmos DB account or the [Cosmos DB emulator](https://docs.microsoft.com/azure/cosmos-db/local-emulator)
+
+## Usage
+
+### Azure (production)
+
+Pass the account endpoint in the URL and the account key in the properties dict:
+
+```python
+import asyncio
+from pynosqlc.core import DriverManager, Filter
+import pynosqlc.cosmosdb  # auto-registers CosmosDriver
+
+async def main():
+    async with await DriverManager.get_client(
+        'pynosqlc:cosmosdb:https://myaccount.documents.azure.com:443/',
+        properties={'key': '<your-account-key>', 'db_id': 'mydb'},
+    ) as client:
+        col = client.get_collection('orders')
+        await col.store('o1', {'item': 'widget', 'qty': 5})
+        f = Filter.where('qty').gt(0).build()
+        async for doc in await col.find(f):
+            print(doc)
+
+asyncio.run(main())
+```
+
+### Cosmos DB Emulator (local)
+
+Use `local` as the target — the driver connects to `http://localhost:8081` with
+the well-known emulator master key automatically:
+
+```python
+async with await DriverManager.get_client(
+    'pynosqlc:cosmosdb:local',
+    properties={'db_id': 'mydb'},
+) as client:
+    ...
+```
+
+## URL scheme
+
+```
+pynosqlc:cosmosdb:<endpoint-or-local>
+```
+
+| Target | Resolves to |
+|---|---|
+| `local` or `localhost` | `http://localhost:8081` with emulator master key |
+| `localhost:PORT` | `http://localhost:PORT` with emulator master key |
+| `https://...` | Azure Cosmos DB account endpoint (requires `key` property) |
+
+Optional properties:
+
+| Key | Description |
+|---|---|
+| `key` | Account key (required for `https://` targets; omitted for emulator) |
+| `db_id` | Database name (default: `'pynosqlc'`) |
+| `endpoint` | Override endpoint URL (for `local`/`localhost` targets) |

alt_python_pynosqlc_cosmosdb-1.0.0/README.md

@@ -0,0 +1,73 @@
+# pynosqlc-cosmosdb
+
+Azure Cosmos DB driver for [pynosqlc](https://github.com/alt-python/pynosqlc) — connects to Azure Cosmos DB (or the local emulator) via the azure-cosmos async client.
+
+## Install
+
+```
+pip install alt-python-pynosqlc-cosmosdb
+```
+
+## Requirements
+
+- Python 3.12+
+- azure-cosmos 4.7+
+- An Azure Cosmos DB account or the [Cosmos DB emulator](https://docs.microsoft.com/azure/cosmos-db/local-emulator)
+
+## Usage
+
+### Azure (production)
+
+Pass the account endpoint in the URL and the account key in the properties dict:
+
+```python
+import asyncio
+from pynosqlc.core import DriverManager, Filter
+import pynosqlc.cosmosdb  # auto-registers CosmosDriver
+
+async def main():
+    async with await DriverManager.get_client(
+        'pynosqlc:cosmosdb:https://myaccount.documents.azure.com:443/',
+        properties={'key': '<your-account-key>', 'db_id': 'mydb'},
+    ) as client:
+        col = client.get_collection('orders')
+        await col.store('o1', {'item': 'widget', 'qty': 5})
+        f = Filter.where('qty').gt(0).build()
+        async for doc in await col.find(f):
+            print(doc)
+
+asyncio.run(main())
+```
+
+### Cosmos DB Emulator (local)
+
+Use `local` as the target — the driver connects to `http://localhost:8081` with
+the well-known emulator master key automatically:
+
+```python
+async with await DriverManager.get_client(
+    'pynosqlc:cosmosdb:local',
+    properties={'db_id': 'mydb'},
+) as client:
+    ...
+```
+
+## URL scheme
+
+```
+pynosqlc:cosmosdb:<endpoint-or-local>
+```
+
+| Target | Resolves to |
+|---|---|
+| `local` or `localhost` | `http://localhost:8081` with emulator master key |
+| `localhost:PORT` | `http://localhost:PORT` with emulator master key |
+| `https://...` | Azure Cosmos DB account endpoint (requires `key` property) |
+
+Optional properties:
+
+| Key | Description |
+|---|---|
+| `key` | Account key (required for `https://` targets; omitted for emulator) |
+| `db_id` | Database name (default: `'pynosqlc'`) |
+| `endpoint` | Override endpoint URL (for `local`/`localhost` targets) |

alt_python_pynosqlc_cosmosdb-1.0.0/pynosqlc/cosmosdb/__init__.py

@@ -0,0 +1,12 @@
+"""
+pynosqlc.cosmosdb — Azure Cosmos DB driver for pynosqlc.
+
+Importing this package auto-registers the CosmosDriver with the global
+DriverManager via the module-level ``_driver`` sentinel in cosmos_driver.py.
+"""
+
+from pynosqlc.cosmosdb.cosmos_driver import CosmosDriver, _driver
+from pynosqlc.cosmosdb.cosmos_client import CosmosClient
+from pynosqlc.cosmosdb.cosmos_collection import CosmosCollection
+
+__all__ = ["CosmosDriver", "CosmosClient", "CosmosCollection", "_driver"]

alt_python_pynosqlc_cosmosdb-1.0.0/pynosqlc/cosmosdb/cosmos_client.py

@@ -0,0 +1,94 @@
+"""
+cosmos_client.py — CosmosClient: a pynosqlc Client backed by azure-cosmos aio.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from azure.cosmos import PartitionKey
+from azure.cosmos.aio import CosmosClient as NativeCosmosClient
+
+from pynosqlc.core.client import Client
+from pynosqlc.cosmosdb.cosmos_collection import CosmosCollection
+
+
+class CosmosClient(Client):
+    """A pynosqlc Client backed by :class:`azure.cosmos.aio.CosmosClient`.
+
+    Args:
+        url: the original ``pynosqlc:cosmosdb:<target>`` URL.
+        endpoint: the Cosmos DB endpoint URL.
+        key: the Cosmos DB account key.
+        db_id: the database name to use (created if it does not exist).
+        client_kwargs: extra keyword arguments forwarded to
+            :class:`azure.cosmos.aio.CosmosClient`.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        endpoint: str,
+        key: str,
+        db_id: str,
+        client_kwargs: dict | None = None,
+    ) -> None:
+        super().__init__({"url": url})
+        self._endpoint = endpoint
+        self._key = key
+        self._db_id = db_id
+        self._client_kwargs: dict = client_kwargs or {}
+        self._native_ctx: NativeCosmosClient | None = None
+        self._database: Any = None
+        self._container_cache: dict[str, Any] = {}
+
+    async def _open(self) -> None:
+        """Open the native Cosmos DB client and resolve the target database.
+
+        Must be called by the driver after constructing this client.
+        """
+        self._native_ctx = NativeCosmosClient(
+            url=self._endpoint,
+            credential=self._key,
+            **self._client_kwargs,
+        )
+        await self._native_ctx.__aenter__()
+        self._database = await self._native_ctx.create_database_if_not_exists(
+            id=self._db_id
+        )
+
+    async def _close(self) -> None:
+        """Exit the native Cosmos DB client context manager."""
+        if self._native_ctx is not None:
+            await self._native_ctx.__aexit__(None, None, None)
+            self._native_ctx = None
+            self._database = None
+            self._container_cache.clear()
+
+    def _get_collection(self, name: str) -> CosmosCollection:
+        """Create and return a :class:`CosmosCollection` for *name*."""
+        return CosmosCollection(self, name)
+
+    async def ensure_container(self, name: str) -> Any:
+        """Return a Cosmos DB container proxy for *name*, creating it if needed.
+
+        Uses ``/id`` as the partition key path.  The container proxy is cached
+        after the first successful call so the SDK round-trip is only paid once
+        per container name per client lifetime.
+
+        Args:
+            name: the container (collection) name.
+
+        Returns:
+            The :class:`azure.cosmos.aio.ContainerProxy` for the container.
+        """
+        if name in self._container_cache:
+            return self._container_cache[name]
+
+        container = await self._database.create_container_if_not_exists(
+            id=name,
+            # PartitionKey must come from azure.cosmos (sync), not azure.cosmos.aio
+            partition_key=PartitionKey(path="/id"),
+        )
+        self._container_cache[name] = container
+        return container

alt_python_pynosqlc_cosmosdb-1.0.0/pynosqlc/cosmosdb/cosmos_collection.py

@@ -0,0 +1,114 @@
+"""
+cosmos_collection.py — CosmosCollection: a pynosqlc Collection backed by a
+Cosmos DB container.
+
+The document primary key is stored as the Cosmos DB item ``id`` field.
+Internal Cosmos DB metadata fields (prefixed with ``_``) are stripped from all
+returned documents.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from azure.cosmos.exceptions import CosmosResourceNotFoundError
+
+from pynosqlc.core.collection import Collection
+from pynosqlc.core.cursor import Cursor
+from pynosqlc.cosmosdb.cosmos_filter_translator import CosmosFilterTranslator
+
+
+def _strip_internal(item: dict) -> dict:
+    """Remove Cosmos DB internal metadata fields (those starting with ``_``).
+
+    The ``id`` field is preserved — it is the user-visible document key.
+
+    Args:
+        item: a raw Cosmos DB item dict.
+
+    Returns:
+        The item with all ``_``-prefixed keys removed.
+    """
+    return {k: v for k, v in item.items() if not k.startswith("_")}
+
+
+class CosmosCollection(Collection):
+    """A pynosqlc Collection backed by a Cosmos DB container.
+
+    The container is created on first access with ``/id`` as the partition key.
+    :meth:`CosmosClient.ensure_container` is called at the start of every
+    operation — it is a no-op after the first successful call.
+
+    Args:
+        client: the owning :class:`~pynosqlc.cosmosdb.CosmosClient`.
+        name: the container / collection name.
+    """
+
+    def __init__(self, client, name: str) -> None:
+        super().__init__(client, name)
+
+    async def _get(self, key: str) -> dict | None:
+        """Retrieve a document by its ``id``."""
+        container = await self._client.ensure_container(self._name)
+        try:
+            item = await container.read_item(item=key, partition_key=key)
+        except CosmosResourceNotFoundError:
+            return None
+        return _strip_internal(item)
+
+    async def _store(self, key: str, doc: dict) -> None:
+        """Upsert a document, setting ``id = key``."""
+        container = await self._client.ensure_container(self._name)
+        await container.upsert_item(body={**doc, "id": key})
+
+    async def _delete(self, key: str) -> None:
+        """Delete the document at ``id = key``.  Silent if not found."""
+        container = await self._client.ensure_container(self._name)
+        try:
+            await container.delete_item(item=key, partition_key=key)
+        except CosmosResourceNotFoundError:
+            pass
+
+    async def _insert(self, doc: dict) -> str:
+        """Insert a document with a generated UUID ``id``; return the id."""
+        container = await self._client.ensure_container(self._name)
+        id_ = str(uuid.uuid4())
+        await container.upsert_item(body={**doc, "id": id_})
+        return id_
+
+    async def _update(self, key: str, patch: dict) -> None:
+        """Patch the document at ``id = key`` by merging *patch* into it.
+
+        Reads the current document, merges the patch (shallow), and upserts.
+        The ``id`` field is always preserved as *key*.
+        """
+        container = await self._client.ensure_container(self._name)
+        existing = await self._get(key) or {}
+        merged = {**existing, **patch, "id": key}
+        await container.upsert_item(body=merged)
+
+    async def _find(self, ast: dict) -> Cursor:
+        """Find documents matching the filter AST.
+
+        Translates the AST to a Cosmos DB SQL WHERE clause, runs the query,
+        strips internal fields from each result, and wraps results in a
+        :class:`~pynosqlc.core.Cursor`.
+        """
+        container = await self._client.ensure_container(self._name)
+
+        where_clause, parameters = CosmosFilterTranslator.translate(ast)
+
+        if where_clause is not None:
+            sql = f"SELECT * FROM c WHERE {where_clause}"
+        else:
+            sql = "SELECT * FROM c"
+
+        docs = [
+            _strip_internal(item)
+            async for item in container.query_items(
+                query=sql,
+                parameters=parameters,
+            )
+        ]
+
+        return Cursor(docs)

alt_python_pynosqlc_cosmosdb-1.0.0/pynosqlc/cosmosdb/cosmos_driver.py

@@ -0,0 +1,92 @@
+"""
+cosmos_driver.py — CosmosDriver: connects to Azure Cosmos DB via azure-cosmos.
+
+URL scheme: pynosqlc:cosmosdb:<target>
+  where <target> is one of:
+    local                 → Cosmos DB emulator at http://localhost:8081
+    localhost             → same as local
+    localhost:PORT        → Cosmos DB emulator at http://localhost:PORT
+    https://...           → Azure Cosmos DB endpoint (requires 'key' property)
+
+Auto-registers with DriverManager on import.
+"""
+
+from __future__ import annotations
+
+from pynosqlc.core.driver import Driver
+from pynosqlc.core.driver_manager import DriverManager
+from pynosqlc.cosmosdb.cosmos_client import CosmosClient
+
+# Well-known Cosmos DB emulator master key.
+_EMULATOR_KEY = (
+    "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
+)
+
+
+class CosmosDriver(Driver):
+    """Driver that creates :class:`CosmosClient` instances.
+
+    URL prefix: ``pynosqlc:cosmosdb:``
+    """
+
+    URL_PREFIX: str = "pynosqlc:cosmosdb:"
+
+    def accepts_url(self, url: str) -> bool:
+        """Return ``True`` for ``'pynosqlc:cosmosdb:'`` URLs."""
+        return isinstance(url, str) and url.startswith(self.URL_PREFIX)
+
+    async def connect(
+        self,
+        url: str,
+        properties: dict | None = None,
+    ) -> CosmosClient:
+        """Create and return an open :class:`CosmosClient`.
+
+        Args:
+            url: ``pynosqlc:cosmosdb:<target>``
+            properties: optional dict; supports:
+                - ``endpoint``: override endpoint URL (for local target)
+                - ``key``: account key (required for https:// target)
+                - ``db_id``: database name (default: ``'pynosqlc'``)
+                - any extra keyword args passed through to
+                  :class:`azure.cosmos.aio.CosmosClient`
+
+        Returns:
+            An open :class:`CosmosClient`.
+
+        Raises:
+            ValueError: if an ``https://`` target is used without ``key``.
+        """
+        props = properties or {}
+
+        target = url[len(self.URL_PREFIX):]
+        db_id = props.pop("db_id", "pynosqlc")
+
+        # Determine endpoint and key from the target string.
+        if target in ("local", "localhost") or target.startswith("localhost:"):
+            # Cosmos DB emulator
+            endpoint = props.pop(
+                "endpoint",
+                "http://localhost:8081",
+            )
+            key = props.pop("key", _EMULATOR_KEY)
+        elif target.startswith("https://"):
+            endpoint = target
+            if "key" not in props:
+                raise ValueError(
+                    f"CosmosDriver: 'key' property is required for endpoint {target!r}"
+                )
+            key = props.pop("key")
+        else:
+            # Treat unknown targets as the endpoint directly.
+            endpoint = target
+            key = props.pop("key", _EMULATOR_KEY)
+
+        client = CosmosClient(url, endpoint, key, db_id, props)
+        await client._open()
+        return client
+
+
+# Auto-register on import — a single shared instance is sufficient.
+_driver = CosmosDriver()
+DriverManager.register_driver(_driver)

alt_python_pynosqlc_cosmosdb-1.0.0/pynosqlc/cosmosdb/cosmos_filter_translator.py

@@ -0,0 +1,211 @@
+"""
+cosmos_filter_translator.py — Translates a pynosqlc Filter AST to a Cosmos DB
+SQL WHERE clause with positional ``@vN`` parameters.
+
+Returns
+-------
+tuple[str | None, list[dict]]
+    ``(where_clause, parameters)``
+
+    * ``where_clause`` is the SQL fragment to embed after ``WHERE``, or
+      ``None`` when the AST matches everything.
+    * ``parameters`` is the list of ``{"name": "@vN", "value": <val>}`` dicts
+      that ``container.query_items(query=..., parameters=...)`` expects.
+
+Design
+------
+A fresh ``_TranslatorState`` is created for each ``translate()`` call.  The
+state carries a single monotonically-increasing ``idx`` counter used for both
+the ``@vN`` parameter names.  Field paths are inlined directly into the SQL
+string using bracket notation (``c["fieldname"]``) so no separate name-alias
+dict is needed.
+
+Bracket notation avoids Cosmos DB reserved-word conflicts and handles field
+names with spaces or special characters.
+
+Supported operators
+-------------------
+eq, ne, gt, gte, lt, lte, contains, in, nin, exists
+
+Composite node types
+--------------------
+and, or, not
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class CosmosFilterTranslator:
+    """Stateless translator from pynosqlc Filter AST to Cosmos DB SQL pair."""
+
+    @staticmethod
+    def translate(
+        ast: dict | None,
+    ) -> tuple[str | None, list[dict]]:
+        """Translate a Filter AST node to a Cosmos DB SQL (clause, params) pair.
+
+        Args:
+            ast: a Filter AST node, or ``None`` / empty dict (matches all).
+
+        Returns:
+            A tuple of ``(where_clause, parameters)``.  When the AST is falsy
+            or has no conditions, returns ``(None, [])``.
+
+        Raises:
+            ValueError: if an unknown AST node type or operator is encountered.
+        """
+        if not ast:
+            return (None, [])
+
+        # An 'and' / 'or' node with an empty conditions list also means "match all"
+        if ast.get("type") in ("and", "or") and not ast.get("conditions"):
+            return (None, [])
+
+        state = _TranslatorState()
+        expr = state._node(ast)
+        if expr is None:
+            return (None, [])
+        return (expr, state.parameters)
+
+
+# ---------------------------------------------------------------------------
+# Internal stateful translator
+# ---------------------------------------------------------------------------
+
+
+class _TranslatorState:
+    """Carries mutable translation state for a single translate() call."""
+
+    def __init__(self) -> None:
+        self.idx: int = 0
+        self.parameters: list[dict] = []
+
+    # ── Counter helpers ──────────────────────────────────────────────────────
+
+    @staticmethod
+    def _field_path(field: str) -> str:
+        """Return the Cosmos SQL bracket-notation path for *field*."""
+        return f'c["{field}"]'
+
+    def _value_alias(self, value: Any) -> str:
+        """Allocate the next @vN alias, record in parameters, and return alias."""
+        alias = f"@v{self.idx}"
+        self.parameters.append({"name": alias, "value": value})
+        self.idx += 1
+        return alias
+
+    # ── Node dispatcher ──────────────────────────────────────────────────────
+
+    def _node(self, ast: dict) -> str | None:
+        """Recursively translate an AST node to a SQL expression string."""
+        node_type = ast.get("type")
+
+        if node_type == "and":
+            return self._and_node(ast)
+
+        if node_type == "or":
+            return self._or_node(ast)
+
+        if node_type == "not":
+            return self._not_node(ast)
+
+        if node_type == "condition":
+            return self._condition(ast)
+
+        raise ValueError(f"Unknown filter AST node type: {node_type!r}")
+
+    # ── Composite nodes ──────────────────────────────────────────────────────
+
+    def _and_node(self, ast: dict) -> str | None:
+        conditions = ast.get("conditions") or []
+        if not conditions:
+            return None
+        parts = [self._node(c) for c in conditions]
+        parts = [p for p in parts if p is not None]
+        if not parts:
+            return None
+        if len(parts) == 1:
+            return parts[0]
+        joined = " AND ".join(f"({p})" for p in parts)
+        return joined
+
+    def _or_node(self, ast: dict) -> str | None:
+        conditions = ast.get("conditions") or []
+        if not conditions:
+            return None
+        parts = [self._node(c) for c in conditions]
+        parts = [p for p in parts if p is not None]
+        if not parts:
+            return None
+        if len(parts) == 1:
+            return parts[0]
+        joined = " OR ".join(f"({p})" for p in parts)
+        return joined
+
+    def _not_node(self, ast: dict) -> str:
+        inner = self._node(ast["condition"])
+        return f"NOT ({inner})"
+
+    # ── Leaf condition ───────────────────────────────────────────────────────
+
+    def _condition(self, node: dict) -> str:
+        field: str = node["field"]
+        op: str = node["op"]
+        value: Any = node.get("value")
+
+        fp = self._field_path(field)
+
+        if op == "eq":
+            va = self._value_alias(value)
+            return f'{fp} = {va}'
+
+        if op == "ne":
+            va = self._value_alias(value)
+            return f'{fp} != {va}'
+
+        if op == "gt":
+            va = self._value_alias(value)
+            return f'{fp} > {va}'
+
+        if op == "gte":
+            va = self._value_alias(value)
+            return f'{fp} >= {va}'
+
+        if op == "lt":
+            va = self._value_alias(value)
+            return f'{fp} < {va}'
+
+        if op == "lte":
+            va = self._value_alias(value)
+            return f'{fp} <= {va}'
+
+        if op == "contains":
+            va = self._value_alias(value)
+            return f'ARRAY_CONTAINS({fp}, {va})'
+
+        if op == "exists":
+            # exists adds no parameter entry
+            if value:
+                return f'IS_DEFINED({fp})'
+            else:
+                return f'NOT IS_DEFINED({fp})'
+
+        if op == "in":
+            values = value or []
+            if not values:
+                return "1=0"
+            aliases = [self._value_alias(v) for v in values]
+            alias_list = ", ".join(aliases)
+            return f'{fp} IN ({alias_list})'
+
+        if op == "nin":
+            values = value or []
+            if not values:
+                return "1=1"
+            aliases = [self._value_alias(v) for v in values]
+            alias_list = ", ".join(aliases)
+            return f'NOT ({fp} IN ({alias_list}))'
+
+        raise ValueError(f"Unknown filter operator: {op!r}")

alt_python_pynosqlc_cosmosdb-1.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "alt-python-pynosqlc-cosmosdb"
+version = "1.0.0"
+description = "CosmosDB driver for pynosqlc"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "alt-python-pynosqlc-core",
+    "azure-cosmos>=4.7",
+]
+authors = [
+    {name = "Craig Parravicini"},
+    {name = "Claude (Anthropic)"},
+]
+license = {text = "MIT"}
+keywords = ["nosql", "database", "async", "cosmosdb", "azure", "driver"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/alt-python/pynosqlc"
+Repository = "https://github.com/alt-python/pynosqlc"
+Documentation = "https://github.com/alt-python/pynosqlc#getting-started"
+"Bug Tracker" = "https://github.com/alt-python/pynosqlc/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pynosqlc"]
+
+[tool.uv.sources]
+alt-python-pynosqlc-core = { workspace = true }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

alt_python_pynosqlc_cosmosdb-1.0.0/tests/test_compliance.py

@@ -0,0 +1,61 @@
+"""
+test_compliance.py — CosmosDB driver compliance tests.
+
+Wires the shared pynosqlc.core compliance suite into the cosmosdb package.
+Each test run gets a fresh CosmosClient connected to a real Cosmos DB instance.
+
+Set COSMOS_ENDPOINT to override the default local endpoint (default: http://localhost:8081).
+Set COSMOS_DB to override the database name (default: pynosqlc_ci).
+Tests are skipped automatically if the Cosmos emulator is not reachable.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from pynosqlc.core import DriverManager
+from pynosqlc.core.testing import run_compliance
+import pynosqlc.cosmosdb  # noqa: F401 — registers CosmosDriver on import
+from pynosqlc.cosmosdb.cosmos_driver import _driver
+
+COSMOS_ENDPOINT = os.environ.get("COSMOS_ENDPOINT", "http://localhost:8081")
+COSMOS_DB = os.environ.get("COSMOS_DB", "pynosqlc_ci")
+COSMOS_URL = "pynosqlc:cosmosdb:local"
+
+
+async def _factory():
+    """Return a fresh, open CosmosClient for each test class fixture.
+
+    Clears and re-registers the driver, connects to Cosmos DB, deletes any
+    leftover compliance containers so ensure_container recreates them cleanly,
+    and returns the client.
+
+    Skips the test if the Cosmos emulator is not reachable.
+    """
+    DriverManager.clear()
+    DriverManager.register_driver(_driver)
+
+    try:
+        client = await DriverManager.get_client(
+            COSMOS_URL,
+            {"db_id": COSMOS_DB, "endpoint": COSMOS_ENDPOINT},
+        )
+    except Exception as e:
+        pytest.skip(f"CosmosDB not available: {e}")
+
+    # Delete compliance containers from any prior run so tests are isolated.
+    # Deleting the container and removing it from the cache forces ensure_container
+    # to recreate it fresh on first use — simpler than clearing items.
+    for name in ("compliance_kv", "compliance_doc", "compliance_find"):
+        try:
+            await client._database.delete_container(name)
+            client._container_cache.pop(name, None)
+        except Exception:
+            pass  # Container may not exist yet; that's fine.
+
+    return client
+
+
+run_compliance(_factory)

alt_python_pynosqlc_cosmosdb-1.0.0/tests/test_cosmos_filter_translator.py

@@ -0,0 +1,378 @@
+"""
+Unit tests for CosmosFilterTranslator.
+
+Covers:
+- All 10 operators: eq, ne, gt, gte, lt, lte, contains, in, nin, exists
+- and-node with 1 condition unwraps (no wrapping parens)
+- and-node with 2 conditions → "(expr1) AND (expr2)"
+- or-node with 1 condition unwraps
+- or-node with 2 conditions → "(expr1) OR (expr2)"
+- not-node → "NOT (expr)"
+- None ast → (None, [])
+- empty dict ast → (None, [])
+- empty and/or conditions → (None, [])
+- in_ multi-value expansion with real SQL IN
+- nin multi-value expansion with NOT (...IN...)
+- in_ with empty list → "1=0"
+- nin with empty list → "1=1"
+- exists(True) / exists(False) add no parameter entry
+- unknown op raises ValueError
+- unknown node type raises ValueError
+- compound filter uses distinct @vN aliases with no collisions
+- bracket notation c["field"] is used for all field paths
+"""
+
+import pytest
+
+from pynosqlc.cosmosdb.cosmos_filter_translator import CosmosFilterTranslator
+
+translate = CosmosFilterTranslator.translate
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def cond(field, op, value=None):
+    """Convenience factory for condition AST nodes."""
+    node = {"type": "condition", "field": field, "op": op}
+    if value is not None:
+        node["value"] = value
+    return node
+
+
+def param(name: str, value) -> dict:
+    """Convenience factory for a Cosmos parameter dict."""
+    return {"name": name, "value": value}
+
+
+# ---------------------------------------------------------------------------
+# None / empty input
+# ---------------------------------------------------------------------------
+
+class TestEmptyInput:
+    def test_none_returns_none_empty(self):
+        assert translate(None) == (None, [])
+
+    def test_empty_dict_returns_none_empty(self):
+        assert translate({}) == (None, [])
+
+    def test_empty_and_conditions_returns_none_empty(self):
+        assert translate({"type": "and", "conditions": []}) == (None, [])
+
+    def test_empty_or_conditions_returns_none_empty(self):
+        assert translate({"type": "or", "conditions": []}) == (None, [])
+
+
+# ---------------------------------------------------------------------------
+# All 10 operators on a regular field
+# ---------------------------------------------------------------------------
+
+class TestOperators:
+    def test_eq(self):
+        expr, params = translate(cond("name", "eq", "Alice"))
+        assert expr == 'c["name"] = @v0'
+        assert params == [param("@v0", "Alice")]
+
+    def test_ne(self):
+        expr, params = translate(cond("status", "ne", "inactive"))
+        assert expr == 'c["status"] != @v0'
+        assert params == [param("@v0", "inactive")]
+
+    def test_gt(self):
+        expr, params = translate(cond("age", "gt", 18))
+        assert expr == 'c["age"] > @v0'
+        assert params == [param("@v0", 18)]
+
+    def test_gte(self):
+        expr, params = translate(cond("score", "gte", 90))
+        assert expr == 'c["score"] >= @v0'
+        assert params == [param("@v0", 90)]
+
+    def test_lt(self):
+        expr, params = translate(cond("price", "lt", 100))
+        assert expr == 'c["price"] < @v0'
+        assert params == [param("@v0", 100)]
+
+    def test_lte(self):
+        expr, params = translate(cond("rank", "lte", 5))
+        assert expr == 'c["rank"] <= @v0'
+        assert params == [param("@v0", 5)]
+
+    def test_contains(self):
+        expr, params = translate(cond("tags", "contains", "python"))
+        assert expr == 'ARRAY_CONTAINS(c["tags"], @v0)'
+        assert params == [param("@v0", "python")]
+
+    def test_exists_true(self):
+        expr, params = translate(cond("email", "exists", True))
+        assert expr == 'IS_DEFINED(c["email"])'
+        assert params == []
+
+    def test_exists_false(self):
+        expr, params = translate(cond("deleted_at", "exists", False))
+        assert expr == 'NOT IS_DEFINED(c["deleted_at"])'
+        assert params == []
+
+    def test_in(self):
+        expr, params = translate(cond("category", "in", ["a", "b", "c"]))
+        assert expr == 'c["category"] IN (@v0, @v1, @v2)'
+        assert params == [
+            param("@v0", "a"),
+            param("@v1", "b"),
+            param("@v2", "c"),
+        ]
+
+    def test_nin(self):
+        expr, params = translate(cond("role", "nin", ["admin", "root"]))
+        assert expr == 'NOT (c["role"] IN (@v0, @v1))'
+        assert params == [
+            param("@v0", "admin"),
+            param("@v1", "root"),
+        ]
+
+
+# ---------------------------------------------------------------------------
+# in / nin expansion and edge cases
+# ---------------------------------------------------------------------------
+
+class TestInNinExpansion:
+    def test_in_single_value(self):
+        expr, params = translate(cond("x", "in", ["only"]))
+        assert expr == 'c["x"] IN (@v0)'
+        assert params == [param("@v0", "only")]
+
+    def test_in_multi_value_aliases_present(self):
+        expr, params = translate(cond("x", "in", [1, 2, 3, 4]))
+        assert expr == 'c["x"] IN (@v0, @v1, @v2, @v3)'
+        assert [p["name"] for p in params] == ["@v0", "@v1", "@v2", "@v3"]
+        assert [p["value"] for p in params] == [1, 2, 3, 4]
+
+    def test_nin_produces_not_in(self):
+        expr, params = translate(cond("status", "nin", ["a", "b"]))
+        assert expr == 'NOT (c["status"] IN (@v0, @v1))'
+        assert params == [param("@v0", "a"), param("@v1", "b")]
+
+    def test_nin_multi_value(self):
+        expr, params = translate(cond("x", "nin", [10, 20, 30]))
+        assert expr == 'NOT (c["x"] IN (@v0, @v1, @v2))'
+        assert params == [
+            param("@v0", 10),
+            param("@v1", 20),
+            param("@v2", 30),
+        ]
+
+    def test_in_empty_list_never_matches(self):
+        expr, params = translate(cond("x", "in", []))
+        assert expr == "1=0"
+        assert params == []
+
+    def test_nin_empty_list_always_matches(self):
+        expr, params = translate(cond("x", "nin", []))
+        assert expr == "1=1"
+        assert params == []
+
+
+# ---------------------------------------------------------------------------
+# exists does not add to parameters
+# ---------------------------------------------------------------------------
+
+class TestExistsNoValue:
+    def test_exists_true_no_parameter(self):
+        _, params = translate(cond("field", "exists", True))
+        assert params == []
+
+    def test_exists_false_no_parameter(self):
+        _, params = translate(cond("field", "exists", False))
+        assert params == []
+
+
+# ---------------------------------------------------------------------------
+# and-node
+# ---------------------------------------------------------------------------
+
+class TestAndNode:
+    def test_single_condition_unwraps(self):
+        node = {"type": "and", "conditions": [cond("x", "eq", 1)]}
+        expr, params = translate(node)
+        assert expr == 'c["x"] = @v0'
+        assert params == [param("@v0", 1)]
+
+    def test_two_conditions_produces_and(self):
+        node = {
+            "type": "and",
+            "conditions": [cond("x", "eq", 1), cond("y", "gt", 0)],
+        }
+        expr, params = translate(node)
+        assert expr == '(c["x"] = @v0) AND (c["y"] > @v1)'
+        assert params == [param("@v0", 1), param("@v1", 0)]
+
+    def test_three_conditions(self):
+        node = {
+            "type": "and",
+            "conditions": [
+                cond("a", "eq", 1),
+                cond("b", "ne", 2),
+                cond("c", "gt", 3),
+            ],
+        }
+        expr, params = translate(node)
+        assert expr == '(c["a"] = @v0) AND (c["b"] != @v1) AND (c["c"] > @v2)'
+        assert len(params) == 3
+
+    def test_empty_conditions_returns_none(self):
+        node = {"type": "and", "conditions": []}
+        assert translate(node) == (None, [])
+
+
+# ---------------------------------------------------------------------------
+# or-node
+# ---------------------------------------------------------------------------
+
+class TestOrNode:
+    def test_single_condition_unwraps(self):
+        node = {"type": "or", "conditions": [cond("x", "eq", 1)]}
+        expr, params = translate(node)
+        assert expr == 'c["x"] = @v0'
+
+    def test_two_conditions_produces_or(self):
+        node = {
+            "type": "or",
+            "conditions": [cond("a", "lt", 5), cond("b", "gte", 10)],
+        }
+        expr, params = translate(node)
+        assert expr == '(c["a"] < @v0) OR (c["b"] >= @v1)'
+        assert params == [param("@v0", 5), param("@v1", 10)]
+
+    def test_empty_conditions_returns_none(self):
+        node = {"type": "or", "conditions": []}
+        assert translate(node) == (None, [])
+
+
+# ---------------------------------------------------------------------------
+# not-node
+# ---------------------------------------------------------------------------
+
+class TestNotNode:
+    def test_not_wraps_with_not(self):
+        node = {"type": "not", "condition": cond("active", "eq", True)}
+        expr, params = translate(node)
+        assert expr == 'NOT (c["active"] = @v0)'
+        assert params == [param("@v0", True)]
+
+    def test_not_with_and_inner(self):
+        inner = {
+            "type": "and",
+            "conditions": [cond("x", "gt", 0), cond("y", "lt", 10)],
+        }
+        node = {"type": "not", "condition": inner}
+        expr, _ = translate(node)
+        assert expr == 'NOT ((c["x"] > @v0) AND (c["y"] < @v1))'
+
+    def test_not_exists(self):
+        node = {"type": "not", "condition": cond("field", "exists", True)}
+        expr, params = translate(node)
+        assert expr == 'NOT (IS_DEFINED(c["field"]))'
+        assert params == []
+
+
+# ---------------------------------------------------------------------------
+# Error cases
+# ---------------------------------------------------------------------------
+
+class TestErrors:
+    def test_unknown_op_raises_value_error(self):
+        with pytest.raises(ValueError, match="Unknown filter operator"):
+            translate(cond("x", "regex", ".*"))
+
+    def test_unknown_node_type_raises_value_error(self):
+        with pytest.raises(ValueError, match="Unknown filter AST node type"):
+            translate({"type": "xor", "conditions": []})
+
+
+# ---------------------------------------------------------------------------
+# Global counter: no alias collisions in compound filters
+# ---------------------------------------------------------------------------
+
+class TestGlobalCounters:
+    def test_distinct_value_aliases_across_fields(self):
+        """A compound filter over three distinct fields must use @v0/@v1/@v2
+        with no collisions, and parameters list preserves insertion order."""
+        node = {
+            "type": "and",
+            "conditions": [
+                cond("alpha", "eq", 1),
+                cond("beta", "gt", 2),
+                cond("gamma", "lte", 3),
+            ],
+        }
+        expr, params = translate(node)
+        assert expr == (
+            '(c["alpha"] = @v0) AND (c["beta"] > @v1) AND (c["gamma"] <= @v2)'
+        )
+        assert params == [
+            param("@v0", 1),
+            param("@v1", 2),
+            param("@v2", 3),
+        ]
+
+    def test_in_then_eq_no_collision(self):
+        """in_ expands multiple @vN aliases; a subsequent field must continue
+        from the correct counter, not restart at @v0."""
+        node = {
+            "type": "and",
+            "conditions": [
+                cond("status", "in", ["a", "b"]),
+                cond("age", "gt", 18),
+            ],
+        }
+        expr, params = translate(node)
+        assert params[0] == param("@v0", "a")
+        assert params[1] == param("@v1", "b")
+        assert params[2] == param("@v2", 18)
+        assert 'c["status"] IN (@v0, @v1)' in expr
+        assert 'c["age"] > @v2' in expr
+
+    def test_exists_does_not_consume_counter(self):
+        """exists must not consume an @vN slot; a following condition must use
+        @v0, not @v1."""
+        node = {
+            "type": "and",
+            "conditions": [
+                cond("email", "exists", True),
+                cond("age", "gt", 18),
+            ],
+        }
+        expr, params = translate(node)
+        # Only one parameter — from the gt condition
+        assert params == [param("@v0", 18)]
+        assert 'IS_DEFINED(c["email"])' in expr
+        assert 'c["age"] > @v0' in expr
+
+    def test_nin_then_eq_no_collision(self):
+        """nin_ expands multiple @vN aliases; subsequent fields continue."""
+        node = {
+            "type": "and",
+            "conditions": [
+                cond("role", "nin", ["admin", "root"]),
+                cond("active", "eq", True),
+            ],
+        }
+        expr, params = translate(node)
+        assert params[0] == param("@v0", "admin")
+        assert params[1] == param("@v1", "root")
+        assert params[2] == param("@v2", True)
+        assert 'NOT (c["role"] IN (@v0, @v1))' in expr
+        assert 'c["active"] = @v2' in expr
+
+    def test_bracket_notation_for_reserved_word_field(self):
+        """Field named 'value' (a Cosmos reserved word) uses bracket notation."""
+        expr, params = translate(cond("value", "eq", 42))
+        assert expr == 'c["value"] = @v0'
+        assert params == [param("@v0", 42)]
+
+    def test_bracket_notation_for_field_with_space(self):
+        """Field names with spaces are valid in bracket notation."""
+        expr, params = translate(cond("first name", "eq", "Bob"))
+        assert expr == 'c["first name"] = @v0'
+        assert params == [param("@v0", "Bob")]