py-key-value-aio 0.2.0__tar.gz

py_key_value_aio-0.2.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.3
+Name: py-key-value-aio
+Version: 0.2.0
+Summary: Async Key-Value
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: py-key-value-shared>=0.2.0
+Requires-Dist: diskcache>=5.6.0 ; extra == 'disk'
+Requires-Dist: pathvalidate>=3.3.1 ; extra == 'disk'
+Requires-Dist: elasticsearch>=9.0.0 ; extra == 'elasticsearch'
+Requires-Dist: aiohttp>=3.12 ; extra == 'elasticsearch'
+Requires-Dist: aiomcache>=0.8.0 ; extra == 'memcached'
+Requires-Dist: cachetools>=6.0.0 ; extra == 'memory'
+Requires-Dist: pymongo>=4.15.0 ; extra == 'mongodb'
+Requires-Dist: pydantic>=2.11.9 ; extra == 'pydantic'
+Requires-Dist: redis>=6.0.0 ; extra == 'redis'
+Requires-Dist: valkey-glide>=2.1.0 ; extra == 'valkey'
+Requires-Python: >=3.10
+Provides-Extra: disk
+Provides-Extra: elasticsearch
+Provides-Extra: memcached
+Provides-Extra: memory
+Provides-Extra: mongodb
+Provides-Extra: pydantic
+Provides-Extra: redis
+Provides-Extra: valkey
+Description-Content-Type: text/markdown
+
+See the root [README.md](../README.md) for more information.

py_key_value_aio-0.2.0/README.md

@@ -0,0 +1 @@
+See the root [README.md](../README.md) for more information.

py_key_value_aio-0.2.0/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "py-key-value-aio"
+version = "0.2.0"
+description = "Async Key-Value"
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "py-key-value-shared>=0.2.0",
+]
+
+
+[build-system]
+requires = ["uv_build>=0.8.2,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "key_value.aio"
+
+[tool.uv.sources]
+py-key-value-shared = { workspace = true }
+py-key-value-shared-test = { workspace = true }
+
+[project.optional-dependencies]
+memory = ["cachetools>=6.0.0"]
+disk = ["diskcache>=5.6.0", "pathvalidate>=3.3.1",]
+redis = ["redis>=6.0.0"]
+mongodb = ["pymongo>=4.15.0"]
+valkey = ["valkey-glide>=2.1.0"]
+memcached = ["aiomcache>=0.8.0"]
+elasticsearch = ["elasticsearch>=9.0.0", "aiohttp>=3.12"]
+pydantic = ["pydantic>=2.11.9"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = ["--inline-snapshot=disable","-vv","-s"]
+markers = [
+    "skip_on_ci: Skip running the test when running on CI",
+]
+timeout = 10
+
+env_files = [".env"]
+
+[dependency-groups]
+dev = [
+    "py-key-value-aio[memory,disk,redis,elasticsearch,memcached,mongodb]",
+    "py-key-value-aio[valkey]; platform_system != 'Windows'",
+    "py-key-value-aio[pydantic]",
+    "pytest",
+    "pytest-mock",
+    "pytest-asyncio",
+    "ruff",
+    "diskcache-stubs>=5.6.3.6.20240818",
+    "pytest-dotenv>=0.5.2",
+    "dirty-equals>=0.10.0",
+    "inline-snapshot>=0.29.0",
+    "pytest-redis>=3.1.3",
+    "basedpyright>=1.31.5",
+    "pytest-timeout>=2.4.0",
+    "ast-comments>=1.2.3",
+    "docker>=7.1.0",
+    "py-key-value-shared-test>=0.2.0",
+    
+]
+lint = [
+  "ruff"
+]
+
+[tool.ruff]
+extend="../../pyproject.toml"
+
+[tool.pyright]
+extends = "../../pyproject.toml"

py_key_value_aio-0.2.0/src/key_value/aio/adapters/__init__.py

@@ -0,0 +1 @@
+

py_key_value_aio-0.2.0/src/key_value/aio/adapters/pydantic/__init__.py

@@ -0,0 +1,3 @@
+from key_value.aio.adapters.pydantic.adapter import PydanticAdapter
+
+__all__ = ["PydanticAdapter"]

py_key_value_aio-0.2.0/src/key_value/aio/adapters/pydantic/adapter.py

@@ -0,0 +1,114 @@
+from collections.abc import Sequence
+from typing import Any, Generic, TypeVar
+
+from key_value.shared.errors import DeserializationError, SerializationError
+from pydantic import BaseModel, ValidationError
+from pydantic_core import PydanticSerializationError
+
+from key_value.aio.protocols.key_value import AsyncKeyValue
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class PydanticAdapter(Generic[T]):
+    """Adapter around a KVStore-compliant Store that allows type-safe persistence of Pydantic models."""
+
+    def __init__(self, key_value: AsyncKeyValue, pydantic_model: type[T], default_collection: str | None = None) -> None:
+        self.key_value: AsyncKeyValue = key_value
+        self.pydantic_model: type[T] = pydantic_model
+        self.default_collection: str | None = default_collection
+
+    def _validate_model(self, value: dict[str, Any]) -> T:
+        try:
+            return self.pydantic_model.model_validate(obj=value)
+        except ValidationError as e:
+            msg = f"Invalid Pydantic model: {e}"
+            raise DeserializationError(msg) from e
+
+    def _serialize_model(self, value: T) -> dict[str, Any]:
+        try:
+            return value.model_dump(mode="json")
+        except PydanticSerializationError as e:
+            msg = f"Invalid Pydantic model: {e}"
+            raise SerializationError(msg) from e
+
+    async def get(self, key: str, *, collection: str | None = None) -> T | None:
+        """Get and validate a model by key.
+
+        Returns the parsed model instance, or None if not present.
+        Raises DeserializationError if the stored data cannot be validated as the model.
+        """
+        collection = collection or self.default_collection
+
+        if value := await self.key_value.get(key=key, collection=collection):
+            return self._validate_model(value=value)
+
+        return None
+
+    async def get_many(self, keys: list[str], *, collection: str | None = None) -> list[T | None]:
+        """Batch get and validate models by keys, preserving order.
+
+        Each element is either a parsed model instance or None if missing.
+        """
+        collection = collection or self.default_collection
+
+        values: list[dict[str, Any] | None] = await self.key_value.get_many(keys=keys, collection=collection)
+
+        return [self._validate_model(value=value) if value else None for value in values]
+
+    async def put(self, key: str, value: T, *, collection: str | None = None, ttl: float | None = None) -> None:
+        """Serialize and store a model.
+
+        Propagates SerializationError if the model cannot be serialized.
+        """
+        collection = collection or self.default_collection
+
+        value_dict: dict[str, Any] = self._serialize_model(value=value)
+
+        await self.key_value.put(key=key, value=value_dict, collection=collection, ttl=ttl)
+
+    async def put_many(self, keys: list[str], values: Sequence[T], *, collection: str | None = None, ttl: float | None = None) -> None:
+        """Serialize and store multiple models, preserving order alignment with keys."""
+        collection = collection or self.default_collection
+
+        value_dicts: list[dict[str, Any]] = [self._serialize_model(value=value) for value in values]
+
+        await self.key_value.put_many(keys=keys, values=value_dicts, collection=collection, ttl=ttl)
+
+    async def delete(self, key: str, *, collection: str | None = None) -> bool:
+        """Delete a model by key. Returns True if a value was deleted, else False."""
+        collection = collection or self.default_collection
+
+        return await self.key_value.delete(key=key, collection=collection)
+
+    async def delete_many(self, keys: list[str], *, collection: str | None = None) -> int:
+        """Delete multiple models by key. Returns the count of deleted entries."""
+        collection = collection or self.default_collection
+
+        return await self.key_value.delete_many(keys=keys, collection=collection)
+
+    async def ttl(self, key: str, *, collection: str | None = None) -> tuple[T | None, float | None]:
+        """Get a model and its TTL seconds if present.
+
+        Returns (model, ttl_seconds) or (None, None) if missing.
+        """
+        collection = collection or self.default_collection
+
+        entry: dict[str, Any] | None
+        ttl_info: float | None
+
+        entry, ttl_info = await self.key_value.ttl(key=key, collection=collection)
+
+        if entry is not None:
+            model_validate: T = self._validate_model(value=entry)
+            return (model_validate, ttl_info)
+
+        return (None, None)
+
+    async def ttl_many(self, keys: list[str], *, collection: str | None = None) -> list[tuple[T | None, float | None]]:
+        """Batch get models with TTLs. Each element is (model|None, ttl_seconds|None)."""
+        collection = collection or self.default_collection
+
+        entries: list[tuple[dict[str, Any] | None, float | None]] = await self.key_value.ttl_many(keys=keys, collection=collection)
+
+        return [(self._validate_model(value=entry) if entry else None, ttl_info) for entry, ttl_info in entries]

py_key_value_aio-0.2.0/src/key_value/aio/adapters/raise_on_missing/__init__.py

@@ -0,0 +1,3 @@
+from key_value.aio.adapters.raise_on_missing.adapter import RaiseOnMissingAdapter
+
+__all__ = ["RaiseOnMissingAdapter"]

py_key_value_aio-0.2.0/src/key_value/aio/adapters/raise_on_missing/adapter.py

@@ -0,0 +1,191 @@
+from collections.abc import Sequence
+from typing import Any, Literal, overload
+
+from key_value.shared.errors import MissingKeyError
+
+from key_value.aio.protocols.key_value import AsyncKeyValue
+
+
+class RaiseOnMissingAdapter:
+    """Adapter around a KVStore that raises on missing values for get/get_many/ttl/ttl_many.
+
+    When `raise_on_missing=True`, methods raise `MissingKeyError` instead of returning None.
+    """
+
+    def __init__(self, key_value: AsyncKeyValue) -> None:
+        self.key_value: AsyncKeyValue = key_value
+
+    @overload
+    async def get(self, key: str, *, collection: str | None = None, raise_on_missing: Literal[False] = False) -> dict[str, Any] | None: ...
+
+    @overload
+    async def get(self, key: str, *, collection: str | None = None, raise_on_missing: Literal[True]) -> dict[str, Any]: ...
+
+    async def get(
+        self,
+        key: str,
+        *,
+        collection: str | None = None,
+        raise_on_missing: bool = False,
+    ) -> dict[str, Any] | None:
+        """Retrieve a value by key from the specified collection.
+
+        Args:
+            key: The key to retrieve the value from.
+            collection: The collection to retrieve the value from. If no collection is provided, it will use the default collection.
+            raise_on_missing: Whether to raise a MissingKeyError if the key is not found.
+
+        Returns:
+            The value associated with the key. If the key is not found, None will be returned.
+        """
+        result = await self.key_value.get(key=key, collection=collection)
+
+        if result is not None:
+            return result
+
+        if raise_on_missing:
+            raise MissingKeyError(operation="get", collection=collection, key=key)
+
+        return None
+
+    @overload
+    async def get_many(
+        self, keys: list[str], *, collection: str | None = None, raise_on_missing: Literal[False] = False
+    ) -> list[dict[str, Any] | None]: ...
+
+    @overload
+    async def get_many(
+        self, keys: list[str], *, collection: str | None = None, raise_on_missing: Literal[True]
+    ) -> list[dict[str, Any]]: ...
+
+    async def get_many(
+        self, keys: list[str], *, collection: str | None = None, raise_on_missing: bool = False
+    ) -> list[dict[str, Any]] | list[dict[str, Any] | None]:
+        """Retrieve multiple values by key from the specified collection.
+
+        Args:
+            keys: The keys to retrieve the values from.
+            collection: The collection to retrieve keys from. If no collection is provided, it will use the default collection.
+
+        Returns:
+            The values for the keys, or [] if the key is not found.
+        """
+        results: list[dict[str, Any] | None] = await self.key_value.get_many(collection=collection, keys=keys)
+
+        for i, key in enumerate(keys):
+            if results[i] is None and raise_on_missing:
+                raise MissingKeyError(operation="get_many", collection=collection, key=key)
+
+        return results
+
+    @overload
+    async def ttl(
+        self, key: str, *, collection: str | None = None, raise_on_missing: Literal[False] = False
+    ) -> tuple[dict[str, Any] | None, float | None]: ...
+
+    @overload
+    async def ttl(
+        self, key: str, *, collection: str | None = None, raise_on_missing: Literal[True]
+    ) -> tuple[dict[str, Any], float | None]: ...
+
+    async def ttl(
+        self, key: str, *, collection: str | None = None, raise_on_missing: bool = False
+    ) -> tuple[dict[str, Any] | None, float | None]:
+        """Retrieve the value and TTL information for a key-value pair from the specified collection.
+
+        Args:
+            key: The key to retrieve the TTL information from.
+            collection: The collection to retrieve the TTL information from. If no collection is provided,
+                        it will use the default collection.
+
+        Returns:
+            The value and TTL information for the key. If the key is not found, (None, None) will be returned.
+        """
+        value, ttl = await self.key_value.ttl(key=key, collection=collection)
+
+        if value is not None:
+            return value, ttl
+
+        if raise_on_missing:
+            raise MissingKeyError(operation="ttl", collection=collection, key=key)
+
+        return (None, None)
+
+    @overload
+    async def ttl_many(
+        self, keys: list[str], *, collection: str | None = None, raise_on_missing: Literal[False] = False
+    ) -> list[tuple[dict[str, Any] | None, float | None]]: ...
+
+    @overload
+    async def ttl_many(
+        self, keys: list[str], *, collection: str | None = None, raise_on_missing: Literal[True]
+    ) -> list[tuple[dict[str, Any], float | None]]: ...
+
+    async def ttl_many(
+        self, keys: list[str], *, collection: str | None = None, raise_on_missing: bool = False
+    ) -> list[tuple[dict[str, Any], float | None]] | list[tuple[dict[str, Any] | None, float | None]]:
+        """Retrieve multiple values and TTL information by key from the specified collection.
+
+        Args:
+            keys: The keys to retrieve the values and TTL information from.
+            collection: The collection to retrieve keys from. If no collection is provided, it will use the default collection.
+        """
+        results: list[tuple[dict[str, Any] | None, float | None]] = await self.key_value.ttl_many(collection=collection, keys=keys)
+
+        for i, key in enumerate(keys):
+            if results[i][0] is None and raise_on_missing:
+                raise MissingKeyError(operation="ttl_many", collection=collection, key=key)
+
+        return results
+
+    async def put(self, key: str, value: dict[str, Any], *, collection: str | None = None, ttl: float | None = None) -> None:
+        """Store a key-value pair in the specified collection with optional TTL.
+
+        Args:
+            key: The key to store the value in.
+            value: The value to store.
+            collection: The collection to store the value in. If no collection is provided, it will use the default collection.
+            ttl: The optional time-to-live (expiry duration) for the key-value pair. Defaults to no TTL. Note: The
+                backend store will convert the provided format to its own internal format.
+        """
+        return await self.key_value.put(key=key, value=value, collection=collection, ttl=ttl)
+
+    async def put_many(
+        self,
+        keys: list[str],
+        values: Sequence[dict[str, Any]],
+        *,
+        collection: str | None = None,
+        ttl: Sequence[float | None] | float | None = None,
+    ) -> None:
+        """Store multiple key-value pairs in the specified collection.
+
+        Args:
+            keys: The keys to store the values in.
+            values: The values to store.
+            collection: The collection to store keys in. If no collection is provided, it will use the default collection.
+            ttl: The optional time-to-live (expiry duration) for the key-value pairs. Defaults to no TTL. Note: The
+                backend store will convert the provided format to its own internal format.
+        """
+        return await self.key_value.put_many(keys=keys, values=values, collection=collection, ttl=ttl)
+
+    async def delete(self, key: str, *, collection: str | None = None) -> bool:
+        """Delete a key-value pair from the specified collection.
+
+        Args:
+            key: The key to delete the value from.
+            collection: The collection to delete the value from. If no collection is provided, it will use the default collection.
+        """
+        return await self.key_value.delete(key=key, collection=collection)
+
+    async def delete_many(self, keys: list[str], *, collection: str | None = None) -> int:
+        """Delete multiple key-value pairs from the specified collection.
+
+        Args:
+            keys: The keys to delete the values from.
+            collection: The collection to delete keys from. If no collection is provided, it will use the default collection.
+
+        Returns:
+            The number of keys deleted.
+        """
+        return await self.key_value.delete_many(keys=keys, collection=collection)

py_key_value_aio-0.2.0/src/key_value/aio/protocols/__init__.py

@@ -0,0 +1 @@
+from key_value.aio.protocols.key_value import AsyncKeyValue as AsyncKeyValue

py_key_value_aio-0.2.0/src/key_value/aio/protocols/key_value.py

@@ -0,0 +1,180 @@
+from collections.abc import Sequence
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class AsyncKeyValueProtocol(Protocol):
+    """A subset of KV operations: get/put/delete and TTL variants, including bulk calls."""
+
+    async def get(
+        self,
+        key: str,
+        *,
+        collection: str | None = None,
+    ) -> dict[str, Any] | None:
+        """Retrieve a value by key from the specified collection.
+
+        Args:
+            key: The key to retrieve the value from.
+            collection: The collection to retrieve the value from. If no collection is provided, it will use the default collection.
+
+        Returns:
+            The value associated with the key. If the key is not found, None will be returned.
+        """
+        ...
+
+    async def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[str, Any] | None, float | None]:
+        """Retrieve the value and TTL information for a key-value pair from the specified collection.
+
+        Args:
+            key: The key to retrieve the TTL information from.
+            collection: The collection to retrieve the TTL information from. If no collection is provided,
+                        it will use the default collection.
+
+        Returns:
+            The value and TTL information for the key. If the key is not found, (None, None) will be returned.
+        """
+        ...
+
+    async def put(self, key: str, value: dict[str, Any], *, collection: str | None = None, ttl: float | None = None) -> None:
+        """Store a key-value pair in the specified collection with optional TTL.
+
+        Args:
+            key: The key to store the value in.
+            value: The value to store.
+            collection: The collection to store the value in. If no collection is provided, it will use the default collection.
+            ttl: The optional time-to-live (expiry duration) for the key-value pair. Defaults to no TTL. Note: The
+                backend store will convert the provided format to its own internal format.
+        """
+        ...
+
+    async def delete(self, key: str, *, collection: str | None = None) -> bool:
+        """Delete a key-value pair from the specified collection.
+
+        Args:
+            key: The key to delete the value from.
+            collection: The collection to delete the value from. If no collection is provided, it will use the default collection.
+        """
+        ...
+
+    async def get_many(self, keys: list[str], *, collection: str | None = None) -> list[dict[str, Any] | None]:
+        """Retrieve multiple values by key from the specified collection.
+
+        Args:
+            keys: The keys to retrieve the values from.
+            collection: The collection to retrieve keys from. If no collection is provided, it will use the default collection.
+
+        Returns:
+            A list of values for the keys. Each value is either a dict or None if the key is not found.
+        """
+        ...
+
+    async def ttl_many(self, keys: list[str], *, collection: str | None = None) -> list[tuple[dict[str, Any] | None, float | None]]:
+        """Retrieve multiple values and TTL information by key from the specified collection.
+
+        Args:
+            keys: The keys to retrieve the values and TTL information from.
+            collection: The collection to retrieve keys from. If no collection is provided, it will use the default collection.
+
+        Returns:
+            A list of tuples containing (value, ttl) for each key. Each tuple contains either (dict, float) or (None, None) if the
+            key is not found.
+        """
+        ...
+
+    async def put_many(
+        self,
+        keys: list[str],
+        values: Sequence[dict[str, Any]],
+        *,
+        collection: str | None = None,
+        ttl: Sequence[float | None] | float | None = None,
+    ) -> None:
+        """Store multiple key-value pairs in the specified collection.
+
+        Args:
+            keys: The keys to store the values in.
+            values: The values to store.
+            collection: The collection to store keys in. If no collection is provided, it will use the default collection.
+            ttl: The optional time-to-live (expiry duration) for the key-value pairs. Defaults to no TTL. Note: The
+                backend store will convert the provided format to its own internal format.
+        """
+        ...
+
+    async def delete_many(self, keys: list[str], *, collection: str | None = None) -> int:
+        """Delete multiple key-value pairs from the specified collection.
+
+        Args:
+            keys: The keys to delete the values from.
+            collection: The collection to delete keys from. If no collection is provided, it will use the default collection.
+
+        Returns:
+            The number of keys deleted.
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncCullProtocol(Protocol):
+    async def cull(self) -> None:
+        """Cull the store.
+
+        This will remove all expired keys from the store.
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncEnumerateKeysProtocol(Protocol):
+    """Protocol segment to enumerate keys in a collection."""
+
+    async def keys(self, collection: str | None = None, *, limit: int | None = None) -> list[str]:
+        """List all keys in the specified collection.
+
+        Args:
+            collection: The collection to list the keys from. If no collection is provided, it will use the default collection.
+            limit: The maximum number of keys to list. The behavior when no limit is provided is store-dependent.
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncEnumerateCollectionsProtocol(Protocol):
+    async def collections(self, *, limit: int | None = None) -> list[str]:
+        """List all available collection names (may include empty collections).
+
+        Args:
+            limit: The maximum number of collections to list. The behavior when no limit is provided is store-dependent.
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncDestroyStoreProtocol(Protocol):
+    """Protocol segment for store-destruction semantics."""
+
+    async def destroy(self) -> bool:
+        """Destroy the keystore.
+
+        This will clear all collections and keys from the store.
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncDestroyCollectionProtocol(Protocol):
+    async def destroy_collection(self, collection: str) -> bool:
+        """Destroy the specified collection.
+
+        Args:
+            collection: The collection to destroy.
+        """
+        ...
+
+
+class AsyncKeyValue(AsyncKeyValueProtocol, Protocol):
+    """A protocol for key-value store operations.
+
+    Includes basic operations: get, put, delete, ttl
+    Includes bulk operations: get_many, put_many, delete_many, ttl_many.
+    """