objbase 0.5.1__tar.gz → 0.5.2__tar.gz

{objbase-0.5.1 → objbase-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: objbase
-Version: 0.5.1
+Version: 0.5.2
 Summary: Damn simple object store for Python dicts and Pydantic models across multiple backends
 Project-URL: Homepage, https://github.com/fm-labs/objbase
 Project-URL: Issues, https://github.com/fm-labs/objbase/issues
@@ -98,7 +98,8 @@ or from their submodules as in the examples below:
 |---|---|
 | `objbase.interface` | `Storage`, `AsyncStorage` protocols and the `Item` type |
 | `objbase.collection` | `Collection` |
-| `objbase.errors` | `CollectionError`, `ItemNotFoundError` |
+| `objbase.errors` | `CollectionError`, `ItemNotFoundError`, `ActionNotFoundError` |
+| `objbase.actions` | `ActionHandler`, `AsyncActionHandler`, `ActionParams`, `load_action_handler` |
 | `objbase.pydantic` | `PydanticCollection`, `AsyncPydanticCollection` (needs `objbase[pydantic]`) |
 | `objbase.storage.{inmemory,local,sqlite,redis,mongodb}` | Sync storage adapters |
 | `objbase.asyncio.collection` | `AsyncCollection` |
@@ -125,6 +126,7 @@ Errors are raised, not returned:
 | `patch` with data that changes the item's `id` | `ValueError` |
 | `patch` a missing item | `objbase.ItemNotFoundError` (a `CollectionError` and a `LookupError`) |
 | The storage backend reports a failed write | `objbase.CollectionError` |
+| `run_action` with an action that isn't registered | `objbase.ActionNotFoundError` (a `CollectionError` and a `LookupError`) |
 
 `CollectionError` is the base class of all objbase errors.
 
@@ -385,6 +387,83 @@ can also be called directly on the storage.
 
 ---
 
+## Actions
+
+An action is a named operation on a single item. Register a handler on a
+collection, then run it by item id:
+
+```python
+from objbase import Collection, InMemoryStorage
+
+
+def set_status(item, params):
+    return {**item, "status": params["status"]}
+
+
+todos = Collection(item_type="todo", storage=InMemoryStorage())
+todos.register_action("set_status", set_status)
+
+todos.save({"id": "1", "title": "Buy milk", "status": "pending"})
+todos.run_action("1", "set_status", {"status": "done"})  # → {"id": "1", ..., "status": "done"}
+```
+
+A handler is called as `handler(item, params)` with the stored item and the
+params (`{}` if none are given):
+
+- If it returns an item, that item **replaces** the stored one (like `save`) and is
+  returned. It must keep the item's `id`, otherwise `ValueError` is raised and nothing is saved.
+- If it returns `None`, nothing is saved and the stored item is returned.
+- Exceptions raised by the handler propagate unchanged.
+
+`run_action` raises `ActionNotFoundError` for an unregistered action and
+`ItemNotFoundError` for a missing item. Actions are registered per collection
+instance; registering a name again replaces its handler. Like `patch`, an action
+reads, changes and writes the item, so it is not atomic across concurrent writers.
+
+On `AsyncCollection`, `run_action` is a coroutine and handlers may be sync or
+async: async handlers are awaited, sync handlers run in a worker thread
+(`asyncio.to_thread`). `Collection` accepts only sync handlers and raises
+`TypeError` for an async one.
+
+```python
+async def set_status(item, params):
+    return {**item, "status": params["status"]}
+
+
+todos = AsyncCollection(item_type="todo", storage=storage)
+todos.register_action("set_status", set_status)
+await todos.run_action("1", "set_status", {"status": "done"})
+```
+
+### Loading handlers from a module
+
+`load_action_handler(module_name, action_name)` imports a module and returns
+the handler from its `actions` mapping (pass `attr_name=` to use another name):
+
+```python
+# myapp/todo_actions.py
+def set_status(item, params):
+    return {**item, "status": params["status"]}
+
+
+actions = {"set_status": set_status}
+```
+
+```python
+from objbase import load_action_handler
+
+todos.register_action("set_status", load_action_handler("myapp.todo_actions", "set_status"))
+```
+
+It raises `ActionNotFoundError` if the module has no such mapping or action, and
+`TypeError` if the entry isn't callable. Errors from importing the module itself
+propagate unchanged. Only pass module names you trust: importing a module runs its code.
+
+Runs are logged at `DEBUG` level on the `objbase.collection` and
+`objbase.asyncio.collection` loggers.
+
+---
+
 ## Examples
 
 Runnable scripts are in [`examples/`](examples/):

{objbase-0.5.1 → objbase-0.5.2}/README.md

@@ -66,7 +66,8 @@ or from their submodules as in the examples below:
 |---|---|
 | `objbase.interface` | `Storage`, `AsyncStorage` protocols and the `Item` type |
 | `objbase.collection` | `Collection` |
-| `objbase.errors` | `CollectionError`, `ItemNotFoundError` |
+| `objbase.errors` | `CollectionError`, `ItemNotFoundError`, `ActionNotFoundError` |
+| `objbase.actions` | `ActionHandler`, `AsyncActionHandler`, `ActionParams`, `load_action_handler` |
 | `objbase.pydantic` | `PydanticCollection`, `AsyncPydanticCollection` (needs `objbase[pydantic]`) |
 | `objbase.storage.{inmemory,local,sqlite,redis,mongodb}` | Sync storage adapters |
 | `objbase.asyncio.collection` | `AsyncCollection` |
@@ -93,6 +94,7 @@ Errors are raised, not returned:
 | `patch` with data that changes the item's `id` | `ValueError` |
 | `patch` a missing item | `objbase.ItemNotFoundError` (a `CollectionError` and a `LookupError`) |
 | The storage backend reports a failed write | `objbase.CollectionError` |
+| `run_action` with an action that isn't registered | `objbase.ActionNotFoundError` (a `CollectionError` and a `LookupError`) |
 
 `CollectionError` is the base class of all objbase errors.
 
@@ -353,6 +355,83 @@ can also be called directly on the storage.
 
 ---
 
+## Actions
+
+An action is a named operation on a single item. Register a handler on a
+collection, then run it by item id:
+
+```python
+from objbase import Collection, InMemoryStorage
+
+
+def set_status(item, params):
+    return {**item, "status": params["status"]}
+
+
+todos = Collection(item_type="todo", storage=InMemoryStorage())
+todos.register_action("set_status", set_status)
+
+todos.save({"id": "1", "title": "Buy milk", "status": "pending"})
+todos.run_action("1", "set_status", {"status": "done"})  # → {"id": "1", ..., "status": "done"}
+```
+
+A handler is called as `handler(item, params)` with the stored item and the
+params (`{}` if none are given):
+
+- If it returns an item, that item **replaces** the stored one (like `save`) and is
+  returned. It must keep the item's `id`, otherwise `ValueError` is raised and nothing is saved.
+- If it returns `None`, nothing is saved and the stored item is returned.
+- Exceptions raised by the handler propagate unchanged.
+
+`run_action` raises `ActionNotFoundError` for an unregistered action and
+`ItemNotFoundError` for a missing item. Actions are registered per collection
+instance; registering a name again replaces its handler. Like `patch`, an action
+reads, changes and writes the item, so it is not atomic across concurrent writers.
+
+On `AsyncCollection`, `run_action` is a coroutine and handlers may be sync or
+async: async handlers are awaited, sync handlers run in a worker thread
+(`asyncio.to_thread`). `Collection` accepts only sync handlers and raises
+`TypeError` for an async one.
+
+```python
+async def set_status(item, params):
+    return {**item, "status": params["status"]}
+
+
+todos = AsyncCollection(item_type="todo", storage=storage)
+todos.register_action("set_status", set_status)
+await todos.run_action("1", "set_status", {"status": "done"})
+```
+
+### Loading handlers from a module
+
+`load_action_handler(module_name, action_name)` imports a module and returns
+the handler from its `actions` mapping (pass `attr_name=` to use another name):
+
+```python
+# myapp/todo_actions.py
+def set_status(item, params):
+    return {**item, "status": params["status"]}
+
+
+actions = {"set_status": set_status}
+```
+
+```python
+from objbase import load_action_handler
+
+todos.register_action("set_status", load_action_handler("myapp.todo_actions", "set_status"))
+```
+
+It raises `ActionNotFoundError` if the module has no such mapping or action, and
+`TypeError` if the entry isn't callable. Errors from importing the module itself
+propagate unchanged. Only pass module names you trust: importing a module runs its code.
+
+Runs are logged at `DEBUG` level on the `objbase.collection` and
+`objbase.asyncio.collection` loggers.
+
+---
+
 ## Examples
 
 Runnable scripts are in [`examples/`](examples/):

{objbase-0.5.1 → objbase-0.5.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "objbase"
-version = "0.5.1"
+version = "0.5.2"
 description = "Damn simple object store for Python dicts and Pydantic models across multiple backends"
 requires-python = ">=3.13"
 dependencies = []

{objbase-0.5.1 → objbase-0.5.2}/src/objbase/__init__.py

@@ -4,13 +4,14 @@ import importlib
 from importlib.metadata import PackageNotFoundError, version
 from typing import TYPE_CHECKING, Any
 
+from objbase.actions import ActionHandler, ActionParams, AsyncActionHandler, load_action_handler
 from objbase.asyncio.collection import AsyncCollection
 from objbase.asyncio.storage.local import AsyncLocalDirectoryStorage, AsyncLocalFileStorage
 from objbase.asyncio.storage.mongodb import AsyncMongoDBStorage
 from objbase.asyncio.storage.redis import AsyncRedisStorage
 from objbase.asyncio.storage.sqlite import AsyncSQLiteStorage
 from objbase.collection import Collection
-from objbase.errors import CollectionError, ItemNotFoundError
+from objbase.errors import ActionNotFoundError, CollectionError, ItemNotFoundError
 from objbase.interface import AsyncStorage, Item, Storage
 from objbase.storage.inmemory import InMemoryStorage
 from objbase.storage.local import LocalDirectoryStorage, LocalFileStorage
@@ -28,6 +29,10 @@ except PackageNotFoundError:  # running from a source tree without installation
     __version__ = "0.0.0"
 
 __all__ = [
+    "ActionHandler",
+    "ActionNotFoundError",
+    "ActionParams",
+    "AsyncActionHandler",
     "AsyncLocalDirectoryStorage",
     "AsyncLocalFileStorage",
     "AsyncCollection",
@@ -48,6 +53,7 @@ __all__ = [
     "PydanticCollection",
     "RedisStorage",
     "SQLiteStorage",
+    "load_action_handler",
 ]
 
 

objbase-0.5.2/src/objbase/actions.py

@@ -0,0 +1,55 @@
+"""Action handlers: named operations registered on a collection and run against one item.
+
+A handler takes the stored item and the action parameters, and returns either the
+updated item, which the collection saves, or ``None`` to leave the item unchanged.
+"""
+
+import importlib
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from objbase.errors import ActionNotFoundError
+from objbase.interface import Item
+
+ActionParams = dict[str, Any]
+"""Parameters passed to an action handler."""
+
+ActionHandler = Callable[[Item, ActionParams], Item | None]
+"""A sync action handler: ``handler(item, params) -> updated item | None``."""
+
+AsyncActionHandler = Callable[[Item, ActionParams], Awaitable[Item | None]]
+"""An async action handler: ``async handler(item, params) -> updated item | None``."""
+
+
+def check_action_name(name: str) -> None:
+    """Raise ``ValueError`` if ``name`` is not a usable action name."""
+    if not name or not isinstance(name, str):
+        raise ValueError("Action name must be a non-empty string.")
+
+
+def check_action_result(id: str, result: Item) -> None:
+    """Raise ``ValueError`` if a handler's returned item does not keep the item id."""
+    if result.get("id") != id:
+        raise ValueError("Action handler must return the item with its id unchanged.")
+
+
+def load_action_handler(module_name: str, action_name: str, attr_name: str = "actions") -> Callable[..., Any]:
+    """Import ``module_name`` and return ``getattr(module, attr_name)[action_name]``.
+
+    The module must define a mapping of action names to handlers (``actions`` by default).
+    The returned handler can be passed to ``register_action``.
+
+    Errors raised while importing the module (``ImportError`` or any error in the
+    module itself) propagate unchanged.
+
+    :raises ActionNotFoundError: If the module has no such mapping or the mapping has no such action.
+    :raises TypeError: If the mapping entry is not callable.
+    """
+    module = importlib.import_module(module_name)
+    actions = getattr(module, attr_name, None)
+    if actions is None or action_name not in actions:
+        raise ActionNotFoundError(action_name, f"module '{module_name}' ({attr_name})")
+    handler = actions[action_name]
+    if not callable(handler):
+        raise TypeError(f"Action '{action_name}' in module '{module_name}' is not callable.")
+    return handler  # type: ignore[no-any-return]

objbase-0.5.2/src/objbase/asyncio/collection.py

@@ -0,0 +1,93 @@
+import asyncio
+import inspect
+import logging
+from typing import cast
+
+from objbase.actions import (
+    ActionHandler,
+    ActionParams,
+    AsyncActionHandler,
+    check_action_name,
+    check_action_result,
+)
+from objbase.collection import check_patch_data, require_item_id, require_read_back
+from objbase.errors import ActionNotFoundError, CollectionError, ItemNotFoundError
+from objbase.interface import AsyncStorage, Item
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncCollection:
+    """Async counterpart of ``Collection``, backed by an ``AsyncStorage``.
+
+    Same methods and behaviour as ``Collection``, but every method is a coroutine.
+    """
+
+    def __init__(self, item_type: str, storage: AsyncStorage):
+        if not isinstance(storage, AsyncStorage):
+            raise TypeError(
+                f"{type(storage).__name__} is not an AsyncStorage; use Collection for sync storage adapters."
+            )
+        self.storage = storage
+        self.item_type = item_type
+        self.actions: dict[str, ActionHandler | AsyncActionHandler] = {}
+
+    async def keys(self) -> list[str]:
+        return await self.storage.akeys(self.item_type)
+
+    async def items(self) -> list[Item]:
+        return await self.storage.aitems(self.item_type)
+
+    async def get(self, id: str) -> Item | None:
+        return await self.storage.aread(self.item_type, id)
+
+    async def save(self, item: Item) -> Item:
+        _id = require_item_id(item)
+        if not await self.storage.awrite(self.item_type, item):
+            raise CollectionError(f"Failed to save item '{_id}'.")
+        return require_read_back(await self.storage.aread(self.item_type, _id), self.item_type, _id)
+
+    async def patch(self, id: str, data: Item) -> Item:
+        check_patch_data(id, data)
+        item = await self.storage.aread(self.item_type, id)
+        if item is None:
+            raise ItemNotFoundError(self.item_type, id)
+        item.update(data)
+        if not await self.storage.awrite(self.item_type, item):
+            raise CollectionError(f"Failed to patch item '{id}'.")
+        return require_read_back(await self.storage.aread(self.item_type, id), self.item_type, id)
+
+    async def delete(self, id: str) -> bool:
+        return await self.storage.adelete(self.item_type, id)
+
+    def register_action(self, name: str, handler: ActionHandler | AsyncActionHandler) -> None:
+        """Register ``handler`` as action ``name``, replacing any handler already registered under that name.
+
+        Async handlers are awaited; sync handlers run in a worker thread (``asyncio.to_thread``).
+        """
+        check_action_name(name)
+        self.actions[name] = handler
+
+    async def run_action(self, id: str, name: str, params: ActionParams | None = None) -> Item:
+        """Run action ``name`` on item ``id`` and return the resulting item.
+
+        If the handler returns an item, it is saved (replacing the stored item) and
+        returned; if it returns ``None``, the stored item is returned unchanged.
+        """
+        handler = self.actions.get(name)
+        if handler is None:
+            raise ActionNotFoundError(name, f"item type '{self.item_type}'")
+        item = await self.storage.aread(self.item_type, id)
+        if item is None:
+            raise ItemNotFoundError(self.item_type, id)
+        logger.debug("Running action %r on %s item %r", name, self.item_type, id)
+        if inspect.iscoroutinefunction(handler):
+            result = await cast(AsyncActionHandler, handler)(item, params or {})
+        else:
+            result = await asyncio.to_thread(cast(ActionHandler, handler), item, params or {})
+        if result is None:
+            logger.debug("Action %r on %s item %r left the item unchanged", name, self.item_type, id)
+            return item
+        check_action_result(id, result)
+        logger.debug("Action %r on %s item %r returned an updated item; saving", name, self.item_type, id)
+        return await self.save(result)

{objbase-0.5.1 → objbase-0.5.2}/src/objbase/collection.py

@@ -1,8 +1,13 @@
+import inspect
+import logging
 from typing import Any
 
-from objbase.errors import CollectionError, ItemNotFoundError
+from objbase.actions import ActionHandler, ActionParams, check_action_name, check_action_result
+from objbase.errors import ActionNotFoundError, CollectionError, ItemNotFoundError
 from objbase.interface import Item, Storage
 
+logger = logging.getLogger(__name__)
+
 
 def require_item_id(item: Item) -> Any:
     """Return the item's id, raising ``ValueError`` if it is missing or empty."""
@@ -29,6 +34,7 @@ class Collection:
     def __init__(self, item_type: str, storage: Storage):
         self.storage = storage
         self.item_type = item_type
+        self.actions: dict[str, ActionHandler] = {}
 
     def keys(self) -> list[str]:
         return self.storage.keys(self.item_type)
@@ -57,3 +63,31 @@ class Collection:
 
     def delete(self, id: str) -> bool:
         return self.storage.delete(self.item_type, id)
+
+    def register_action(self, name: str, handler: ActionHandler) -> None:
+        """Register ``handler`` as action ``name``, replacing any handler already registered under that name."""
+        check_action_name(name)
+        if inspect.iscoroutinefunction(handler):
+            raise TypeError(f"Action '{name}' has an async handler; register it on an AsyncCollection instead.")
+        self.actions[name] = handler
+
+    def run_action(self, id: str, name: str, params: ActionParams | None = None) -> Item:
+        """Run action ``name`` on item ``id`` and return the resulting item.
+
+        If the handler returns an item, it is saved (replacing the stored item) and
+        returned; if it returns ``None``, the stored item is returned unchanged.
+        """
+        handler = self.actions.get(name)
+        if handler is None:
+            raise ActionNotFoundError(name, f"item type '{self.item_type}'")
+        item = self.storage.read(self.item_type, id)
+        if item is None:
+            raise ItemNotFoundError(self.item_type, id)
+        logger.debug("Running action %r on %s item %r", name, self.item_type, id)
+        result = handler(item, params or {})
+        if result is None:
+            logger.debug("Action %r on %s item %r left the item unchanged", name, self.item_type, id)
+            return item
+        check_action_result(id, result)
+        logger.debug("Action %r on %s item %r returned an updated item; saving", name, self.item_type, id)
+        return self.save(result)

{objbase-0.5.1 → objbase-0.5.2}/src/objbase/errors.py

@@ -9,3 +9,12 @@ class ItemNotFoundError(CollectionError, LookupError):
         self.item_type = item_type
         self.id = id
         super().__init__(f"Item '{id}' of type '{item_type}' not found.")
+
+
+class ActionNotFoundError(CollectionError, LookupError):
+    """Raised when an action is not registered on a collection or not found in a module."""
+
+    def __init__(self, action: str, source: str):
+        self.action = action
+        self.source = source
+        super().__init__(f"Action '{action}' not found for {source}.")

objbase-0.5.2/tests/test_actions.py

@@ -0,0 +1,229 @@
+"""Tests for action handlers on Collection and AsyncCollection, and load_action_handler."""
+
+import logging
+import threading
+
+import pytest
+
+from objbase.actions import load_action_handler
+from objbase.asyncio.collection import AsyncCollection
+from objbase.collection import Collection
+from objbase.errors import ActionNotFoundError, CollectionError, ItemNotFoundError
+from objbase.storage.inmemory import InMemoryStorage
+
+
+def set_status(item, params):
+    return {**item, "status": params["status"]}
+
+
+def no_change(item, params):
+    return None
+
+
+async def async_set_status(item, params):
+    return {**item, "status": params["status"]}
+
+
+@pytest.fixture()
+def storage() -> InMemoryStorage:
+    return InMemoryStorage()
+
+
+@pytest.fixture()
+def todos(storage) -> Collection:
+    todos = Collection(item_type="todo", storage=storage)
+    todos.save({"id": "1", "status": "pending"})
+    return todos
+
+
+@pytest.fixture()
+def async_todos(storage) -> AsyncCollection:
+    storage.write("todo", {"id": "1", "status": "pending"})
+    return AsyncCollection(item_type="todo", storage=storage)
+
+
+# ===========================================================================
+# Collection
+# ===========================================================================
+
+
+class TestCollectionRegisterAction:
+    def test_registers_handler(self, todos):
+        todos.register_action("set_status", set_status)
+        assert todos.actions == {"set_status": set_status}
+
+    def test_registering_again_replaces_handler(self, todos):
+        todos.register_action("act", set_status)
+        todos.register_action("act", no_change)
+        assert todos.actions["act"] is no_change
+
+    def test_actions_are_per_collection(self, storage, todos):
+        todos.register_action("set_status", set_status)
+        assert Collection(item_type="note", storage=storage).actions == {}
+
+    def test_empty_name_raises(self, todos):
+        with pytest.raises(ValueError):
+            todos.register_action("", set_status)
+
+    def test_async_handler_raises_type_error(self, todos):
+        with pytest.raises(TypeError, match="AsyncCollection"):
+            todos.register_action("set_status", async_set_status)
+
+
+class TestCollectionRunAction:
+    def test_returned_item_is_saved_and_returned(self, todos):
+        todos.register_action("set_status", set_status)
+        assert todos.run_action("1", "set_status", {"status": "done"}) == {"id": "1", "status": "done"}
+        assert todos.get("1") == {"id": "1", "status": "done"}
+
+    def test_none_leaves_item_unchanged(self, todos):
+        todos.register_action("noop", no_change)
+        assert todos.run_action("1", "noop") == {"id": "1", "status": "pending"}
+        assert todos.get("1") == {"id": "1", "status": "pending"}
+
+    def test_params_default_to_empty_dict(self, todos):
+        received = []
+        todos.register_action("record", lambda item, params: received.append(params))
+        todos.run_action("1", "record")
+        assert received == [{}]
+
+    def test_handler_receives_stored_item(self, todos):
+        received = []
+        todos.register_action("record", lambda item, params: received.append(item))
+        todos.run_action("1", "record")
+        assert received == [{"id": "1", "status": "pending"}]
+
+    def test_unknown_action_raises(self, todos):
+        with pytest.raises(ActionNotFoundError) as exc_info:
+            todos.run_action("1", "missing")
+        assert exc_info.value.action == "missing"
+        assert isinstance(exc_info.value, CollectionError)
+        assert isinstance(exc_info.value, LookupError)
+
+    def test_unknown_action_checked_before_item(self, todos):
+        with pytest.raises(ActionNotFoundError):
+            todos.run_action("nonexistent", "missing")
+
+    def test_missing_item_raises(self, todos):
+        todos.register_action("set_status", set_status)
+        with pytest.raises(ItemNotFoundError):
+            todos.run_action("nonexistent", "set_status", {"status": "done"})
+
+    @pytest.mark.parametrize("result", [{"id": "2", "status": "done"}, {"status": "done"}])
+    def test_changing_or_dropping_id_raises(self, todos, result):
+        todos.register_action("bad", lambda item, params: result)
+        with pytest.raises(ValueError):
+            todos.run_action("1", "bad")
+        assert todos.get("1") == {"id": "1", "status": "pending"}
+        assert todos.get("2") is None
+
+    def test_handler_errors_propagate(self, todos):
+        todos.register_action("set_status", set_status)
+        with pytest.raises(KeyError):
+            todos.run_action("1", "set_status", {})
+        assert todos.get("1") == {"id": "1", "status": "pending"}
+
+    def test_logs_at_debug_level(self, todos, caplog):
+        todos.register_action("set_status", set_status)
+        with caplog.at_level(logging.DEBUG, logger="objbase"):
+            todos.run_action("1", "set_status", {"status": "done"})
+        assert any("set_status" in record.getMessage() for record in caplog.records)
+        assert all(record.levelno == logging.DEBUG for record in caplog.records)
+
+
+# ===========================================================================
+# AsyncCollection
+# ===========================================================================
+
+
+class TestAsyncCollectionActions:
+    async def test_async_handler_result_is_saved(self, async_todos):
+        async_todos.register_action("set_status", async_set_status)
+        assert await async_todos.run_action("1", "set_status", {"status": "done"}) == {"id": "1", "status": "done"}
+        assert await async_todos.get("1") == {"id": "1", "status": "done"}
+
+    async def test_sync_handler_runs_in_worker_thread(self, async_todos):
+        threads = []
+
+        def handler(item, params):
+            threads.append(threading.current_thread())
+            return set_status(item, params)
+
+        async_todos.register_action("set_status", handler)
+        assert await async_todos.run_action("1", "set_status", {"status": "done"}) == {"id": "1", "status": "done"}
+        assert threads and threads[0] is not threading.main_thread()
+
+    async def test_none_leaves_item_unchanged(self, async_todos):
+        async_todos.register_action("noop", no_change)
+        assert await async_todos.run_action("1", "noop") == {"id": "1", "status": "pending"}
+
+    async def test_unknown_action_raises(self, async_todos):
+        with pytest.raises(ActionNotFoundError):
+            await async_todos.run_action("1", "missing")
+
+    async def test_missing_item_raises(self, async_todos):
+        async_todos.register_action("set_status", async_set_status)
+        with pytest.raises(ItemNotFoundError):
+            await async_todos.run_action("nonexistent", "set_status", {"status": "done"})
+
+    async def test_changing_id_raises(self, async_todos):
+        async def bad(item, params):
+            return {"id": "2"}
+
+        async_todos.register_action("bad", bad)
+        with pytest.raises(ValueError):
+            await async_todos.run_action("1", "bad")
+        assert await async_todos.get("2") is None
+
+    def test_empty_name_raises(self, async_todos):
+        with pytest.raises(ValueError):
+            async_todos.register_action("", set_status)
+
+
+# ===========================================================================
+# load_action_handler
+# ===========================================================================
+
+
+@pytest.fixture()
+def actions_module(tmp_path, monkeypatch):
+    (tmp_path / "my_todo_actions.py").write_text(
+        "def set_status(item, params):\n"
+        "    return {**item, 'status': params['status']}\n"
+        "\n"
+        "actions = {'set_status': set_status, 'broken': 42}\n"
+        "handlers = {'other': set_status}\n"
+    )
+    (tmp_path / "my_failing_actions.py").write_text("import does_not_exist_anywhere\n")
+    monkeypatch.syspath_prepend(str(tmp_path))
+    return "my_todo_actions"
+
+
+class TestLoadActionHandler:
+    def test_loads_handler_from_actions_mapping(self, actions_module, todos):
+        handler = load_action_handler(actions_module, "set_status")
+        todos.register_action("set_status", handler)
+        assert todos.run_action("1", "set_status", {"status": "done"})["status"] == "done"
+
+    def test_custom_attr_name(self, actions_module):
+        assert callable(load_action_handler(actions_module, "other", attr_name="handlers"))
+
+    def test_unknown_action_raises(self, actions_module):
+        with pytest.raises(ActionNotFoundError, match="missing"):
+            load_action_handler(actions_module, "missing")
+
+    def test_missing_mapping_raises(self, actions_module):
+        with pytest.raises(ActionNotFoundError):
+            load_action_handler(actions_module, "set_status", attr_name="nope")
+
+    def test_non_callable_raises(self, actions_module):
+        with pytest.raises(TypeError):
+            load_action_handler(actions_module, "broken")
+
+    def test_missing_module_raises_import_error(self):
+        with pytest.raises(ModuleNotFoundError):
+            load_action_handler("objbase_no_such_module", "set_status")
+
+    def test_import_errors_inside_module_propagate(self, actions_module):
+        with pytest.raises(ModuleNotFoundError, match="does_not_exist_anywhere"):
+            load_action_handler("my_failing_actions", "set_status")

{objbase-0.5.1 → objbase-0.5.2}/uv.lock

@@ -414,7 +414,7 @@ wheels = [
 
 [[package]]
 name = "objbase"
-version = "0.5.1"
+version = "0.5.2"
 source = { editable = "." }
 
 [package.optional-dependencies]

objbase-0.5.1/src/objbase/asyncio/collection.py

@@ -1,46 +0,0 @@
-from objbase.collection import check_patch_data, require_item_id, require_read_back
-from objbase.errors import CollectionError, ItemNotFoundError
-from objbase.interface import AsyncStorage, Item
-
-
-class AsyncCollection:
-    """Async counterpart of ``Collection``, backed by an ``AsyncStorage``.
-
-    Same methods and behaviour as ``Collection``, but every method is a coroutine.
-    """
-
-    def __init__(self, item_type: str, storage: AsyncStorage):
-        if not isinstance(storage, AsyncStorage):
-            raise TypeError(
-                f"{type(storage).__name__} is not an AsyncStorage; use Collection for sync storage adapters."
-            )
-        self.storage = storage
-        self.item_type = item_type
-
-    async def keys(self) -> list[str]:
-        return await self.storage.akeys(self.item_type)
-
-    async def items(self) -> list[Item]:
-        return await self.storage.aitems(self.item_type)
-
-    async def get(self, id: str) -> Item | None:
-        return await self.storage.aread(self.item_type, id)
-
-    async def save(self, item: Item) -> Item:
-        _id = require_item_id(item)
-        if not await self.storage.awrite(self.item_type, item):
-            raise CollectionError(f"Failed to save item '{_id}'.")
-        return require_read_back(await self.storage.aread(self.item_type, _id), self.item_type, _id)
-
-    async def patch(self, id: str, data: Item) -> Item:
-        check_patch_data(id, data)
-        item = await self.storage.aread(self.item_type, id)
-        if item is None:
-            raise ItemNotFoundError(self.item_type, id)
-        item.update(data)
-        if not await self.storage.awrite(self.item_type, item):
-            raise CollectionError(f"Failed to patch item '{id}'.")
-        return require_read_back(await self.storage.aread(self.item_type, id), self.item_type, id)
-
-    async def delete(self, id: str) -> bool:
-        return await self.storage.adelete(self.item_type, id)