alt-python-pynosqlc-core 1.0.4__tar.gz

alt_python_pynosqlc_core-1.0.4/.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_core-1.0.4/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,5 @@
+# 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/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",
+]

alt_python_pynosqlc_core-1.0.4/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

alt_python_pynosqlc_core-1.0.4/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")

alt_python_pynosqlc_core-1.0.4/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"
+            )

alt_python_pynosqlc_core-1.0.4/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)
+        """

alt_python_pynosqlc_core-1.0.4/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 = []

alt_python_pynosqlc_core-1.0.4/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.
+    """