Merge pull request #24 from mutating/develop

0.0.20

Author: pomponchik

README.md

@@ -366,6 +366,28 @@ some_slot['non_existent_key']()
 #> run the slot default function
 ```
 
+When a slot or selection should resolve to exactly one callable candidate, prefer `.one` to manual collection checks. It works on slots and on selections returned by `[...]` or `pop()`:
+
+```python
+@slot
+def sum_slot(a, b) -> list[int]:
+    ...
+
+@sum_slot.plugin
+def sum_plugin(a, b) -> int:
+    return a + b
+
+selected_from_slot = sum_slot.one
+selected_by_name = sum_slot['sum_plugin'].one
+
+print(selected_from_slot(1, 2))
+#> [3]
+print(selected_by_name(1, 2))
+#> [3]
+```
+
+`.one` returns a callable selection; it does not call it. The arguments above are passed to that returned selection. For `sum_slot.one`, the selection contains the only plugin registered in the slot; for `sum_slot['sum_plugin'].one`, the only plugin in that selection. If no plugin matches but the slot body is non-empty, that body is used as fallback. Otherwise, or if there is more than one candidate, `pristan.errors.OneResolutionError` is raised.
+
 You can use the [`len()`](https://docs.python.org/3/library/functions.html#len) function to find out how many plugins you have:
 
 ```python

docs/plans/1.md

@@ -49,11 +49,15 @@ def __bool__(self) -> bool: ...
     def __len__(self) -> int: ...
 
 
-class SlotSelectionProtocol(BaseSlotViewProtocol[SlotParameters, SlotCallResultCovariant, PluginResultCovariant], Protocol[SlotParameters, SlotCallResultCovariant, PluginResultCovariant]):
-    pass
+class SlotSelectionProtocol(BaseSlotViewProtocol[SlotParameters, SlotCallResultCovariant, PluginResultCovariant], Protocol[SlotParameters, SlotCallResultCovariant, PluginResultCovariant]):  # pragma: no cover
+    @property
+    def one(self) -> 'SlotSelectionProtocol[SlotParameters, SlotCallResultCovariant, PluginResultCovariant]': ...
 
 
 class SlotProtocol(BaseSlotViewProtocol[SlotParameters, SlotCallResultCovariant, PluginResult], Protocol[SlotParameters, SlotCallResultCovariant, PluginResult]):  # pragma: no cover
+    @property
+    def one(self) -> SlotSelectionProtocol[SlotParameters, SlotCallResultCovariant, PluginResult]: ...
+
     @overload
     def plugin(self, plugin_function_or_name: Optional[str] = None, unique: bool = False, engine: Optional[Union[List[str], str]] = None, run_once: bool = False) -> Callable[[Callable[SlotParameters, PluginResult]], Callable[SlotParameters, PluginResult]]: ...
 

pristan/common_types.py

@@ -14,6 +14,7 @@
     Generator,
     Generic,
     List,
+    NoReturn,
     Optional,
     Tuple,
     TypeVar,
@@ -37,12 +38,16 @@
 )
 from pristan.components.plugin import Plugin
 from pristan.components.plugins_group import PluginsGroup
-from pristan.components.slot_caller import CallerWithPlugins, SlotCaller
+from pristan.components.slot_caller import (
+    CallerWithPlugins,
+    SlotCaller,
+)
 from pristan.components.slot_code_representer import SlotCodeRepresenter
 from pristan.components.slot_code_representer import sentinel as return_type_sentinel
 from pristan.errors import (
     EntrypointLoadingError,
     ExplicitNameRequiredError,
+    OneResolutionError,
     PrimadonnaPluginError,
     PristanException,
     StrangeTypeAnnotationError,
@@ -109,6 +114,24 @@ def __bool__(self) -> bool:
         self._load_entrypoints()
         return bool(self.backed_caller)
 
+    @property
+    def one(self) -> CallerWithPlugins[PluginResult]:
+        self._load_entrypoints()
+        snapshot = CallerWithPlugins(self.caller, list(self.plugins.plugins))
+        if not snapshot:
+            raise OneResolutionError(f'Slot "{self.slot_name}" has no registered plugins and its body is empty.')
+        if len(snapshot) > 1:
+            raise OneResolutionError(f'Slot "{self.slot_name}" has {len(snapshot)} registered plugins, so .one cannot choose one.')
+        return snapshot
+
+    @one.setter
+    def one(self, value: Any) -> NoReturn:  # noqa: ARG002
+        raise AttributeError('Attribute ".one" is read-only.')
+
+    @one.deleter
+    def one(self) -> NoReturn:
+        raise AttributeError('Attribute ".one" is read-only.')
+
     def __iter__(self) -> Generator[PluginProtocol[SlotParameters, PluginResult], None, None]:
         self._load_entrypoints()
         yield from self.plugins

pristan/components/slot.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict, Generator, Generic, List, Type, Union
+from typing import Any, Dict, Generator, Generic, List, NoReturn, Type, Union
 
 from denial import InnerNoneType
 from printo import repred
@@ -13,6 +13,7 @@
 from pristan.components.plugins_group import PluginsGroup
 from pristan.components.slot_code_representer import SlotCodeRepresenter
 from pristan.components.slot_code_representer import sentinel as return_type_sentinel
+from pristan.errors import OneResolutionError
 
 
 @repred
@@ -78,3 +79,19 @@ def __bool__(self) -> bool:
 
     def __len__(self) -> int:
         return len(self.plugins)
+
+    @property
+    def one(self) -> 'CallerWithPlugins[PluginResult]':
+        if not self:
+            raise OneResolutionError(f'Selection from slot "{self.caller.slot_name}" has no selected plugins and the slot body is empty.')
+        if len(self) > 1:
+            raise OneResolutionError(f'Selection from slot "{self.caller.slot_name}" has {len(self)} selected plugins, so .one cannot choose one.')
+        return self
+
+    @one.setter
+    def one(self, value: Any) -> NoReturn:  # noqa: ARG002
+        raise AttributeError('Attribute ".one" is read-only.')
+
+    @one.deleter
+    def one(self) -> NoReturn:
+        raise AttributeError('Attribute ".one" is read-only.')

pristan/components/slot_caller.py

@@ -28,3 +28,7 @@ class CannotGetVersionsError(PristanException):
 
 class NumberOfCallsError(PristanException):
     ...
+
+
+class OneResolutionError(PristanException):
+    ...

pristan/errors.py

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pristan"
-version = "0.0.19"
+version = "0.0.20"
 authors = [{ name = "Evgeniy Blinov", email = "zheni-b@yandex.ru" }]
 description = "Function-based plugin system with respect to typing"
 readme = "README.md"

pyproject.toml

@@ -0,0 +1,6 @@
+from tests.smokes.demo.simple_slots import simple_slot_3
+
+
+@simple_slot_3.plugin('name')
+def plugin() -> int:
+    return 1

tests/smokes/demo/simple_call_plugins.py

@@ -0,0 +1,6 @@
+from tests.smokes.demo.simple_slots import simple_custom_one_slot
+
+
+@simple_custom_one_slot.plugin('name2')
+def plugin() -> int:
+    return 8

tests/smokes/demo/simple_custom_one_plugins.py

@@ -0,0 +1,6 @@
+from tests.smokes.demo.simple_slots import simple_slot_5
+
+
+@simple_slot_5.plugin('name')
+def plugin() -> int:
+    return 1