mongospec 0.2__tar.gz → 0.2.2__tar.gz

{mongospec-0.2/mongospec.egg-info → mongospec-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mongospec
-Version: 0.2
+Version: 0.2.2
 Summary: Async MongoDB ODM with msgspec integration and automatic collection binding
 Author-email: Diprog <diprog991@gmail.com>
 License-Expression: MIT
@@ -51,6 +51,7 @@ Minimal **async** MongoDB ODM built for *speed* and *simplicity*, featuring auto
    - [CRUD Operations](#crud-operations)  
    - [Indexes](#indexes)
    - [Lifecycle Hooks](#lifecycle-hooks)
+   - [Contrib: KV Store](#contrib-kv-store)
 6. [Contributing](#contributing)
 7. [License](#license)
 
@@ -271,6 +272,67 @@ in sync — no caller-side boilerplate needed.
 
 ---
 
+### Contrib: KV Store
+
+`mongospec.contrib.kv_store` provides a ready-made async key-value store
+backed by a MongoDB collection. Designed for multiple inheritance with
+project-specific base documents.
+
+```python
+from mongospec.contrib.kv_store import KVStore, KVStoreItem
+from myapp.db import Document  # your base with timestamps, hooks, etc.
+
+
+class AppStorage(KVStore, Document):
+    __collection_name__ = "app_storage"
+```
+
+A unique index on `key` is created automatically at init time.
+
+**Direct usage:**
+
+```python
+await AppStorage.set("theme", "dark")
+theme = await AppStorage.get("theme")            # "dark"
+theme = await AppStorage.get_or_default("x", 0)  # 0 (no KeyError)
+await AppStorage.set_default("theme", "light")   # "dark" (atomic, no overwrite)
+
+await AppStorage.set_many({"a": 1, "b": 2})
+all_pairs = await AppStorage.get_all()            # {"theme": "dark", "a": 1, "b": 2}
+all_keys  = await AppStorage.keys()               # ["theme", "a", "b"]
+
+await AppStorage.has("theme")                     # True
+await AppStorage.delete_key("theme")              # True
+```
+
+**Typed accessor (`KVStoreItem`):**
+
+```python
+AppStorageItem = KVStoreItem.of(AppStorage)
+
+max_retries = AppStorageItem[int]("max_retries", default=3)
+
+value = await max_retries.get()          # 3 (default, not persisted)
+await max_retries.set_default()          # atomically persist default if missing
+await max_retries.set(10)
+await max_retries.has()                  # True
+await max_retries.delete()               # True
+```
+
+| `KVStore` method | Description |
+|------------------|-------------|
+| `set(key, value)` | Upsert a value by key |
+| `get(key)` | Get value or raise `KeyError` |
+| `get_or_default(key, default)` | Get value or return default |
+| `set_default(key, value)` | Atomic insert-if-absent (`$setOnInsert`) |
+| `delete_key(key)` | Delete a key, return `True` if existed |
+| `has(key)` | Check key existence |
+| `get_all()` | Return all pairs as `dict` |
+| `keys()` | Return all key names |
+| `set_many(items)` | Upsert multiple pairs |
+
+---
+
 ## Contributing
 
 Contributions, issues and feature requests are welcome.

{mongospec-0.2 → mongospec-0.2.2}/README.md

@@ -24,6 +24,7 @@ Minimal **async** MongoDB ODM built for *speed* and *simplicity*, featuring auto
    - [CRUD Operations](#crud-operations)  
    - [Indexes](#indexes)
    - [Lifecycle Hooks](#lifecycle-hooks)
+   - [Contrib: KV Store](#contrib-kv-store)
 6. [Contributing](#contributing)
 7. [License](#license)
 
@@ -244,6 +245,67 @@ in sync — no caller-side boilerplate needed.
 
 ---
 
+### Contrib: KV Store
+
+`mongospec.contrib.kv_store` provides a ready-made async key-value store
+backed by a MongoDB collection. Designed for multiple inheritance with
+project-specific base documents.
+
+```python
+from mongospec.contrib.kv_store import KVStore, KVStoreItem
+from myapp.db import Document  # your base with timestamps, hooks, etc.
+
+
+class AppStorage(KVStore, Document):
+    __collection_name__ = "app_storage"
+```
+
+A unique index on `key` is created automatically at init time.
+
+**Direct usage:**
+
+```python
+await AppStorage.set("theme", "dark")
+theme = await AppStorage.get("theme")            # "dark"
+theme = await AppStorage.get_or_default("x", 0)  # 0 (no KeyError)
+await AppStorage.set_default("theme", "light")   # "dark" (atomic, no overwrite)
+
+await AppStorage.set_many({"a": 1, "b": 2})
+all_pairs = await AppStorage.get_all()            # {"theme": "dark", "a": 1, "b": 2}
+all_keys  = await AppStorage.keys()               # ["theme", "a", "b"]
+
+await AppStorage.has("theme")                     # True
+await AppStorage.delete_key("theme")              # True
+```
+
+**Typed accessor (`KVStoreItem`):**
+
+```python
+AppStorageItem = KVStoreItem.of(AppStorage)
+
+max_retries = AppStorageItem[int]("max_retries", default=3)
+
+value = await max_retries.get()          # 3 (default, not persisted)
+await max_retries.set_default()          # atomically persist default if missing
+await max_retries.set(10)
+await max_retries.has()                  # True
+await max_retries.delete()               # True
+```
+
+| `KVStore` method | Description |
+|------------------|-------------|
+| `set(key, value)` | Upsert a value by key |
+| `get(key)` | Get value or raise `KeyError` |
+| `get_or_default(key, default)` | Get value or return default |
+| `set_default(key, value)` | Atomic insert-if-absent (`$setOnInsert`) |
+| `delete_key(key)` | Delete a key, return `True` if existed |
+| `has(key)` | Check key existence |
+| `get_all()` | Return all pairs as `dict` |
+| `keys()` | Return all key names |
+| `set_many(items)` | Upsert multiple pairs |
+
+---
+
 ## Contributing
 
 Contributions, issues and feature requests are welcome.

mongospec-0.2.2/mongospec/contrib/kv_store.py

@@ -0,0 +1,280 @@
+"""
+Key-value store built on top of MongoDocument.
+
+Provides a simple async key-value interface over a MongoDB collection.
+Designed for use via multiple inheritance with project-specific base documents.
+
+.. code-block:: python
+
+    from mongospec.contrib.kv_store import KVStoreMixin, KVStoreItem
+
+    class AppStorage(KVStoreMixin, Document):
+        __collection_name__ = "app_storage"
+
+    max_retries = KVStoreItem[int](AppStorage, "max_retries", default=3)
+    value = await max_retries.get()
+    await max_retries.set(5)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, ClassVar, Generic, TypeVar
+
+import mongojet
+
+from mongospec.document.document import MongoDocument
+
+T = TypeVar("T")
+
+
+class KVStoreMixin:
+    """
+    Mixin providing async key-value store methods.
+
+    Does **not** define struct fields — safe for multiple inheritance
+    with any ``MongoDocument`` subclass. The concrete class must define
+    ``key: str`` and ``value: Any | None`` fields.
+
+    .. code-block:: python
+
+        class AppStorage(KVStoreMixin, Document):
+            __collection_name__ = "app_storage"
+
+        await AppStorage.set("theme", "dark")
+        theme = await AppStorage.get("theme")
+    """
+
+    __indexes__: ClassVar[Sequence[mongojet.IndexModel]] = [
+        mongojet.IndexModel(keys=[("key", 1)], unique=True),  # type: ignore[call-arg]
+    ]
+
+    @classmethod
+    async def set(cls, key: str, value: Any | None) -> None:
+        """
+        Upsert a value by key.
+
+        :param key: Unique setting key.
+        :param value: Value to store; may be ``None``.
+        """
+        await cls.update_one(
+            {"key": key},
+            {"$set": {"value": value}},
+            upsert=True,
+        )
+
+    @classmethod
+    async def get(cls, key: str) -> Any | None:
+        """
+        Retrieve a value by key.
+
+        :param key: Unique setting key.
+        :return: The stored value (may be ``None``).
+        :raises KeyError: If the key does not exist.
+        """
+        document = await cls.find_one({"key": key})
+        if document is None:
+            raise KeyError(key)
+        return document.value
+
+    @classmethod
+    async def get_or_default(cls, key: str, default: Any | None = None) -> Any | None:
+        """
+        Retrieve a value by key, returning *default* if missing.
+
+        Unlike :meth:`get`, this never raises :exc:`KeyError`.
+
+        :param key: Unique setting key.
+        :param default: Fallback value when the key is absent.
+        :return: The stored value or *default*.
+        """
+        document = await cls.find_one({"key": key})
+        if document is None:
+            return default
+        return document.value
+
+    @classmethod
+    async def set_default(cls, key: str, value: Any | None) -> Any | None:
+        """
+        Atomically set a value only if the key does not already exist.
+
+        :param key: Unique setting key.
+        :param value: Value to store when the key is missing.
+        :return: The existing value if present, otherwise *value*.
+        """
+        doc = await cls.find_one_and_update(
+            {"key": key},
+            {"$setOnInsert": {"key": key, "value": value}},
+            upsert=True,
+            return_updated=True,
+        )
+        return doc.value if doc is not None else value
+
+    @classmethod
+    async def delete_key(cls, key: str) -> bool:
+        """
+        Delete a key-value pair.
+
+        :param key: Unique setting key.
+        :return: ``True`` if the key existed and was deleted.
+        """
+        return await cls.delete_one({"key": key}) > 0
+
+    @classmethod
+    async def has(cls, key: str) -> bool:
+        """
+        Check whether a key exists.
+
+        :param key: Unique setting key.
+        :return: ``True`` if the key is present.
+        """
+        return await cls.exists({"key": key})
+
+    @classmethod
+    async def get_all(cls) -> dict[str, Any | None]:
+        """
+        Retrieve all key-value pairs as a dictionary.
+
+        :return: Mapping of all stored keys to their values.
+        """
+        docs = await cls.find_all({})
+        return {doc.key: doc.value for doc in docs}
+
+    @classmethod
+    async def keys(cls) -> list[str]:
+        """
+        Retrieve all stored keys.
+
+        :return: List of key names.
+        """
+        docs = await cls.find_all({})
+        return [doc.key for doc in docs]
+
+    @classmethod
+    async def set_many(cls, items: dict[str, Any | None]) -> None:
+        """
+        Upsert multiple key-value pairs at once.
+
+        :param items: Mapping of keys to values.
+        """
+        for key, value in items.items():
+            await cls.set(key, value)
+
+
+class KVStore(KVStoreMixin, MongoDocument, kw_only=True):
+    """
+    Standalone async key-value store backed by a MongoDB collection.
+
+    Includes ``key`` and ``value`` fields. Use this directly if you
+    don't need to combine with a custom base document.
+    For multiple inheritance with your own ``Document`` base, use
+    :class:`KVStoreMixin` instead.
+
+    .. code-block:: python
+
+        class AppStorage(KVStore):
+            __collection_name__ = "app_storage"
+    """
+
+    key: str
+    value: Any | None = None
+
+
+class KVStoreItem(Generic[T]):
+    """
+    Typed accessor for a single key in a :class:`KVStoreMixin` collection.
+
+    .. code-block:: python
+
+        max_retries = KVStoreItem[int](AppStorage, "max_retries", default=3)
+
+        value = await max_retries.get()   # int | None
+        await max_retries.set(10)
+
+    :param store: The ``KVStoreMixin`` subclass to use.
+    :param key: Unique setting key.
+    :param default: Default value returned (and persisted) when the key is missing.
+    """
+
+    def __init__(
+        self,
+        store: type[KVStoreMixin],
+        key: str,
+        default: T | None = None,
+    ) -> None:
+        self._store = store
+        self._key = key
+        self._default = default
+
+    @classmethod
+    def of(cls, store: type[KVStoreMixin]) -> type[KVStoreItem]:
+        """
+        Create a ``KVStoreItem`` subclass bound to a specific store.
+
+        .. code-block:: python
+
+            AppStorageItem = KVStoreItem.of(AppStorage)
+            max_retries = AppStorageItem[int]("max_retries", default=3)
+
+        :param store: The ``KVStoreMixin`` subclass to bind.
+        :return: A new ``KVStoreItem`` subclass with *store* pre-filled.
+        """
+        bound_store = store
+
+        class BoundKVStoreItem(cls):  # type: ignore[misc]
+            def __init__(
+                self,
+                key: str,
+                default: T | None = None,
+            ) -> None:
+                super().__init__(store=bound_store, key=key, default=default)
+
+            def __class_getitem__(cls, item: Any) -> type:
+                return cls
+
+        BoundKVStoreItem.__name__ = f"{store.__name__}Item"
+        BoundKVStoreItem.__qualname__ = f"{store.__name__}Item"
+        return BoundKVStoreItem
+
+    async def get(self) -> T | None:
+        """
+        Get the stored value, returning *default* if missing.
+
+        Does **not** persist the default — use :meth:`set_default`
+        to atomically initialize a key.
+
+        :return: The stored value cast to ``T``, or the default.
+        """
+        return await self._store.get_or_default(self._key, self._default)  # type: ignore[return-value]
+
+    async def set(self, value: T | None) -> None:
+        """
+        Set the stored value.
+
+        :param value: New value to store; may be ``None``.
+        """
+        await self._store.set(self._key, value)
+
+    async def set_default(self) -> T | None:
+        """
+        Atomically persist *default* only if the key is missing.
+
+        :return: The existing value if present, otherwise the default.
+        """
+        return await self._store.set_default(self._key, self._default)  # type: ignore[return-value]
+
+    async def delete(self) -> bool:
+        """
+        Delete the key from the store.
+
+        :return: ``True`` if the key existed.
+        """
+        return await self._store.delete_key(self._key)
+
+    async def has(self) -> bool:
+        """
+        Check whether the key exists.
+
+        :return: ``True`` if the key is present.
+        """
+        return await self._store.has(self._key)

{mongospec-0.2 → mongospec-0.2.2}/mongospec/document/document.py

@@ -10,6 +10,7 @@ from typing import Any, ClassVar, Self, Sequence, final
 import mongojet
 import msgspec
 from bson import ObjectId, int64
+from msgspec._core import StructMeta
 
 from .operations import (
     CountOperationsMixin, DeleteOperationsMixin, FindOperationsMixin,
@@ -17,6 +18,20 @@ from .operations import (
 )
 
 
+class _AutoKwOnlyMeta(StructMeta):
+    """Metaclass that propagates ``kw_only=True`` to all subclasses.
+
+    ``msgspec.Struct`` only inherits ``kw_only`` one level deep.
+    This metaclass ensures it is applied at every depth automatically,
+    unless explicitly overridden with ``kw_only=False``.
+    """
+
+    def __new__(mcs, name: str, bases: tuple[type, ...], namespace: dict[str, Any], **kwargs: Any) -> type:
+        if any(isinstance(b, type) and issubclass(b, msgspec.Struct) for b in bases):
+            kwargs.setdefault("kw_only", True)
+        return super().__new__(mcs, name, bases, namespace, **kwargs)
+
+
 def default_dec_hook(expected_type: type, obj: Any) -> Any:
     """Default decoding hook for basic type conversion.
 
@@ -56,7 +71,8 @@ class MongoDocument(
     FindOperationsMixin,
     InsertOperationsMixin,
     UpdateOperationsMixin,
-    kw_only=True
+    metaclass=_AutoKwOnlyMeta,
+    kw_only=True,
 ):
     """
     Abstract base document for MongoDB collections with automatic binding.

{mongospec-0.2 → mongospec-0.2.2/mongospec.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mongospec
-Version: 0.2
+Version: 0.2.2
 Summary: Async MongoDB ODM with msgspec integration and automatic collection binding
 Author-email: Diprog <diprog991@gmail.com>
 License-Expression: MIT
@@ -51,6 +51,7 @@ Minimal **async** MongoDB ODM built for *speed* and *simplicity*, featuring auto
    - [CRUD Operations](#crud-operations)  
    - [Indexes](#indexes)
    - [Lifecycle Hooks](#lifecycle-hooks)
+   - [Contrib: KV Store](#contrib-kv-store)
 6. [Contributing](#contributing)
 7. [License](#license)
 
@@ -271,6 +272,67 @@ in sync — no caller-side boilerplate needed.
 
 ---
 
+### Contrib: KV Store
+
+`mongospec.contrib.kv_store` provides a ready-made async key-value store
+backed by a MongoDB collection. Designed for multiple inheritance with
+project-specific base documents.
+
+```python
+from mongospec.contrib.kv_store import KVStore, KVStoreItem
+from myapp.db import Document  # your base with timestamps, hooks, etc.
+
+
+class AppStorage(KVStore, Document):
+    __collection_name__ = "app_storage"
+```
+
+A unique index on `key` is created automatically at init time.
+
+**Direct usage:**
+
+```python
+await AppStorage.set("theme", "dark")
+theme = await AppStorage.get("theme")            # "dark"
+theme = await AppStorage.get_or_default("x", 0)  # 0 (no KeyError)
+await AppStorage.set_default("theme", "light")   # "dark" (atomic, no overwrite)
+
+await AppStorage.set_many({"a": 1, "b": 2})
+all_pairs = await AppStorage.get_all()            # {"theme": "dark", "a": 1, "b": 2}
+all_keys  = await AppStorage.keys()               # ["theme", "a", "b"]
+
+await AppStorage.has("theme")                     # True
+await AppStorage.delete_key("theme")              # True
+```
+
+**Typed accessor (`KVStoreItem`):**
+
+```python
+AppStorageItem = KVStoreItem.of(AppStorage)
+
+max_retries = AppStorageItem[int]("max_retries", default=3)
+
+value = await max_retries.get()          # 3 (default, not persisted)
+await max_retries.set_default()          # atomically persist default if missing
+await max_retries.set(10)
+await max_retries.has()                  # True
+await max_retries.delete()               # True
+```
+
+| `KVStore` method | Description |
+|------------------|-------------|
+| `set(key, value)` | Upsert a value by key |
+| `get(key)` | Get value or raise `KeyError` |
+| `get_or_default(key, default)` | Get value or return default |
+| `set_default(key, value)` | Atomic insert-if-absent (`$setOnInsert`) |
+| `delete_key(key)` | Delete a key, return `True` if existed |
+| `has(key)` | Check key existence |
+| `get_all()` | Return all pairs as `dict` |
+| `keys()` | Return all key names |
+| `set_many(items)` | Upsert multiple pairs |
+
+---
+
 ## Contributing
 
 Contributions, issues and feature requests are welcome.

{mongospec-0.2 → mongospec-0.2.2}/mongospec.egg-info/SOURCES.txt

@@ -24,6 +24,8 @@ mongospec.egg-info/SOURCES.txt
 mongospec.egg-info/dependency_links.txt
 mongospec.egg-info/requires.txt
 mongospec.egg-info/top_level.txt
+mongospec/contrib/__init__.py
+mongospec/contrib/kv_store.py
 mongospec/document/__init__.py
 mongospec/document/document.py
 mongospec/document/operations/__init__.py

{mongospec-0.2 → mongospec-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mongospec"
-version = "0.2"
+version = "0.2.2"
 authors = [
     {name = "Diprog", email = "diprog991@gmail.com"}
 ]