Merge pull request #23 from mutating/develop

0.0.19

Author: pomponchik

README.md

@@ -456,6 +456,21 @@ def plugin_2():
 #> pristan.errors.PrimadonnaPluginError: Slot "some_slot" requires unique plugin names, but "plugin" is already registered.
 ```
 
+If every plugin must declare its name manually, pass `explicit_plugin_names=True` to the slot decorator:
+
+```python
+@slot(explicit_plugin_names=True)
+def some_slot():
+    ...
+
+@some_slot.plugin
+def plugin():
+    ...
+
+#> ...
+#> pristan.errors.ExplicitNameRequiredError: Slot "some_slot" requires explicit plugin names.
+```
+
 You can also restrict a plugin to a specific version of the library that declares the slot. To do this, pass a version expression (or a `list` of them) as the `engine` argument:
 
 ```python

pristan/components/slot.py

@@ -42,6 +42,7 @@
 from pristan.components.slot_code_representer import sentinel as return_type_sentinel
 from pristan.errors import (
     EntrypointLoadingError,
+    ExplicitNameRequiredError,
     PrimadonnaPluginError,
     PristanException,
     StrangeTypeAnnotationError,
@@ -65,10 +66,11 @@
         'type_check': lambda x: x != True,
         'entrypoint_group': lambda x: x != 'pristan',
         'unique': lambda x: x,
+        'explicit_plugin_names': lambda x: x,
     },
 )
 class Slot(Generic[PluginResult]):
-    def __init__(self, slot_function: SlotFunction[SlotParameters, SlotResult[PluginResult]], signature: Optional[SlotSignature], slot_name: Optional[str], max: Optional[int], type_check: bool, entrypoint_group: str, unique: bool) -> None:  # noqa: PLR0913, A002
+    def __init__(self, slot_function: SlotFunction[SlotParameters, SlotResult[PluginResult]], *, signature: Optional[SlotSignature], slot_name: Optional[str], max: Optional[int], type_check: bool, entrypoint_group: str, unique: bool, explicit_plugin_names: bool = False) -> None:  # noqa: PLR0913, A002
         if max is not None and max < 0:
             raise ValueError('The maximum number of plugins cannot be less than zero.')
 
@@ -87,6 +89,7 @@ def __init__(self, slot_function: SlotFunction[SlotParameters, SlotResult[Plugin
         self.type_check = type_check
         self.entrypoint_group = entrypoint_group
         self.unique = unique
+        self.explicit_plugin_names = explicit_plugin_names
 
         self.lock = RLock()
 
@@ -168,6 +171,9 @@ def plugin(self, plugin_function_or_name: Optional[Union[PluginFunction[SlotPara
         else:
             raise TypeError('Only a function or plugin name followed by a function can be passed to the decorator.')
 
+        if self.explicit_plugin_names and not isinstance(plugin_function_or_name, str):
+            raise ExplicitNameRequiredError(f'Slot "{self.slot_name}" requires explicit plugin names.')
+
         def decorator(plugin_function: Callable[SlotParameters, PluginResult]) -> Callable[SlotParameters, PluginResult]:
             # TODO: consider to delete this "type: ignore" if python 3.8 deleted from the matrix
             self._compare_signatures(self.slot_function, plugin_function)  # type: ignore[arg-type]

pristan/decorators/slot.py

@@ -12,24 +12,24 @@
 
 
 @overload
-def slot(function: Callable[SlotParameters, List[PluginResult]], /, *, signature: Optional[SlotSignature] = None, name: Optional[str] = None, max: Optional[int] = None, type_check: bool = True, entrypoint_group: str = 'pristan', unique: bool = False) -> SlotProtocol[SlotParameters, List[PluginResult], PluginResult]: ...  # pragma: no branch, PLR0913, A002
+def slot(function: Callable[SlotParameters, List[PluginResult]], /, *, signature: Optional[SlotSignature] = None, name: Optional[str] = None, max: Optional[int] = None, type_check: bool = True, entrypoint_group: str = 'pristan', unique: bool = False, explicit_plugin_names: bool = False) -> SlotProtocol[SlotParameters, List[PluginResult], PluginResult]: ...  # pragma: no branch, PLR0913, A002
 
 @overload
-def slot(function: Callable[SlotParameters, Dict[str, PluginResult]], /, *, signature: Optional[SlotSignature] = None, name: Optional[str] = None, max: Optional[int] = None, type_check: bool = True, entrypoint_group: str = 'pristan', unique: bool = False) -> SlotProtocol[SlotParameters, Dict[str, PluginResult], PluginResult]: ...  # pragma: no branch, PLR0913, A002
+def slot(function: Callable[SlotParameters, Dict[str, PluginResult]], /, *, signature: Optional[SlotSignature] = None, name: Optional[str] = None, max: Optional[int] = None, type_check: bool = True, entrypoint_group: str = 'pristan', unique: bool = False, explicit_plugin_names: bool = False) -> SlotProtocol[SlotParameters, Dict[str, PluginResult], PluginResult]: ...  # pragma: no branch, PLR0913, A002
 
 @overload
-def slot(function: Callable[SlotParameters, None], /, *, signature: Optional[SlotSignature] = None, name: Optional[str] = None, max: Optional[int] = None, type_check: bool = True, entrypoint_group: str = 'pristan', unique: bool = False) -> SlotProtocol[SlotParameters, None, Any]: ...  # pragma: no branch, PLR0913, A002
+def slot(function: Callable[SlotParameters, None], /, *, signature: Optional[SlotSignature] = None, name: Optional[str] = None, max: Optional[int] = None, type_check: bool = True, entrypoint_group: str = 'pristan', unique: bool = False, explicit_plugin_names: bool = False) -> SlotProtocol[SlotParameters, None, Any]: ...  # pragma: no branch, PLR0913, A002
 
 @overload
-def slot(function: str = ..., /, *, signature: Optional[SlotSignature] = None, name: Optional[str] = None, max: Optional[int] = None, type_check: bool = True, entrypoint_group: str = 'pristan', unique: bool = False) -> SlotDecoratorProtocol: ...  # pragma: no branch, PLR0913, A002
+def slot(function: str = ..., /, *, signature: Optional[SlotSignature] = None, name: Optional[str] = None, max: Optional[int] = None, type_check: bool = True, entrypoint_group: str = 'pristan', unique: bool = False, explicit_plugin_names: bool = False) -> SlotDecoratorProtocol: ...  # pragma: no branch, PLR0913, A002
 
-def slot(function: Optional[object] = None, /, *, signature: Optional[SlotSignature] = None, name: Optional[str] = None, max: Optional[int] = None, type_check: bool = True, entrypoint_group: str = 'pristan', unique: bool = False) -> Any:  # noqa: PLR0913, A002
+def slot(function: Optional[object] = None, /, *, signature: Optional[SlotSignature] = None, name: Optional[str] = None, max: Optional[int] = None, type_check: bool = True, entrypoint_group: str = 'pristan', unique: bool = False, explicit_plugin_names: bool = False) -> Any:  # noqa: PLR0913, A002
     if callable(function):
-        return wraps(function)(Slot(function, signature, name, max, type_check, entrypoint_group, unique))
+        return wraps(function)(Slot(function, signature=signature, slot_name=name, max=max, type_check=type_check, entrypoint_group=entrypoint_group, unique=unique, explicit_plugin_names=explicit_plugin_names))
 
     if isinstance(function, str):
         if name is not None and name != function:
             raise ValueError('You have specified two different names for the slot.')
         name = function
 
-    return partial(slot, signature=signature, name=name, max=max, type_check=type_check, entrypoint_group=entrypoint_group, unique=unique)
+    return partial(slot, signature=signature, name=name, max=max, type_check=type_check, entrypoint_group=entrypoint_group, unique=unique, explicit_plugin_names=explicit_plugin_names)

pristan/errors.py

@@ -10,6 +10,10 @@ class PrimadonnaPluginError(PristanException):
     ...
 
 
+class ExplicitNameRequiredError(PristanException, NameError):
+    ...
+
+
 class EntrypointLoadingError(PristanException):
     ...
 

pyproject.toml

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

tests/smokes/demo/simple_explicit_plugin_names_plugins.py

@@ -0,0 +1,6 @@
+from tests.smokes.demo.simple_slots import simple_explicit_plugin_names_slot
+
+
+@simple_explicit_plugin_names_slot.plugin
+def plugin():
+    return 1

tests/smokes/demo/simple_slots.py

@@ -36,3 +36,8 @@ def simple_slot_6() -> Dict[str, int]:
 @slot
 def simple_bool_slot() -> Dict[str, int]:
     return {}
+
+
+@slot(explicit_plugin_names=True)
+def simple_explicit_plugin_names_slot() -> Dict[str, int]:
+    return {}

tests/smokes/test_entry_points.py

@@ -6,9 +6,14 @@
 
 import pristan.components.slot as slot_module
 from pristan import slot
-from pristan.errors import EntrypointLoadingError, PrimadonnaPluginError
+from pristan.errors import (
+    EntrypointLoadingError,
+    ExplicitNameRequiredError,
+    PrimadonnaPluginError,
+)
 from tests.smokes.demo.simple_slots import (
     simple_bool_slot,
+    simple_explicit_plugin_names_slot,
     simple_slot_1,
     simple_slot_2,
     simple_slot_3,
@@ -198,3 +203,36 @@ def get_entries(group=None):  # noqa: ARG001
         simple_slot_6.plugins.plugins_by_requested_names.clear()
         simple_slot_6.loaded = False
         sys.modules.pop(module_name, None)
+
+
+def test_explicit_plugin_names_rejects_inferred_name_loaded_from_entrypoint(monkeypatch):
+    """A real EntryPoint preserves strict plugin-name registration errors."""
+    module_name = 'tests.smokes.demo.simple_explicit_plugin_names_plugins'
+
+    def get_entries(group=None):  # noqa: ARG001
+        return [
+            EntryPoint(
+                name='entrypoint_name',
+                value=module_name,
+                group='pristan',
+            ),
+        ]
+
+    monkeypatch.setattr(slot_module, 'entry_points', get_entries)
+
+    def reset_slot():
+        simple_explicit_plugin_names_slot.plugins.plugins.clear()
+        simple_explicit_plugin_names_slot.plugins.plugins_by_requested_names.clear()
+        simple_explicit_plugin_names_slot.loaded = False
+        sys.modules.pop(module_name, None)
+
+    reset_slot()
+
+    try:
+        with pytest.raises(ExplicitNameRequiredError, match=match('Slot "simple_explicit_plugin_names_slot" requires explicit plugin names.')):
+            simple_explicit_plugin_names_slot()
+
+        assert not simple_explicit_plugin_names_slot.loaded
+        assert len(simple_explicit_plugin_names_slot) == 0
+    finally:
+        reset_slot()

tests/typing/components/test_slot.py

@@ -10,6 +10,6 @@ def test_concrete_slot_bool_method_is_typed_as_bool():
     def collect() -> list:
         return []
 
-    slot_view = Slot(collect, None, None, None, True, 'pristan', False)
+    slot_view = Slot(collect, signature=None, slot_name=None, max=None, type_check=True, entrypoint_group='pristan', unique=False)
 
     reveal_type(slot_view.__bool__())  # R: builtins.bool

tests/typing/decorators/test_slot.py

@@ -79,7 +79,7 @@ def plugin_with_parentheses(value: int) -> int:
 
 
 @pytest.mark.mypy_testing
-def test_slot_configuration_arguments_are_typed():
+def test_slot_configuration_arguments_include_explicit_plugin_names():
     @slot('some_another_slot_name')
     def slot_with_positional_name(value: int) -> List[int]:  # noqa: ARG001
         return []
@@ -96,6 +96,10 @@ def slot_with_keyword_name(value: int) -> Dict[str, int]:  # noqa: ARG001
     def unique_slot(value: int) -> List[int]:  # noqa: ARG001
         return []
 
+    @slot(explicit_plugin_names=True)
+    def explicit_plugin_names_slot(value: int) -> List[int]:  # noqa: ARG001
+        return []
+
     @slot(signature='.', max=1, type_check=False, entrypoint_group='new_namespace', unique=True)
     def configured_slot(value: int) -> List[int]:  # noqa: ARG001
         return []
@@ -108,24 +112,25 @@ def configured_slot_with_signature_list(value: int, context: str = '') -> List[i
     reveal_type(unique_slot_with_positional_name(1))  # R: builtins.list[builtins.int]
     reveal_type(slot_with_keyword_name(1))  # R: builtins.dict[builtins.str, builtins.int]
     reveal_type(unique_slot(1))  # R: builtins.list[builtins.int]
+    reveal_type(explicit_plugin_names_slot(1))  # R: builtins.list[builtins.int]
     reveal_type(configured_slot(1))  # R: builtins.list[builtins.int]
     reveal_type(configured_slot_with_signature_list(1))  # R: builtins.list[builtins.int]
     reveal_type(configured_slot_with_signature_list(1, 'context'))  # R: builtins.list[builtins.int]
     configured_slot_with_signature_list(1, 2)  # E: [arg-type]
 
 
 @pytest.mark.mypy_testing
-def test_slot_direct_call_configuration_arguments_are_typed():
+def test_slot_direct_call_configuration_arguments_include_explicit_plugin_names():
     """Direct-call slot overloads preserve call and plugin result types.
 
     The configured direct-call form accepts the same keyword options as the
-    decorator-factory form, including `unique`. Assignments and reveal checks
-    cover default and configured direct calls, signature strings and lists,
-    custom options, precise list and dict results, and the unannotated `Any`
-    result. The `typed_notify` block keeps the static `None` expectation covered
-    while documenting the current runtime `StrangeTypeAnnotationError`.
-    Iteration over slots with signature lists proves that plugin result types
-    are kept as well.
+    decorator-factory form, including `unique` and `explicit_plugin_names`.
+    Assignments and reveal checks cover default and configured direct calls,
+    signature strings and lists, custom options, precise list and dict results,
+    and the unannotated `Any` result. The `typed_notify` block keeps the static
+    `None` expectation covered while documenting the current runtime
+    `StrangeTypeAnnotationError`. Iteration over slots with signature lists
+    proves that plugin result types are kept as well.
     """
     def collect_list(value: int) -> List[int]:  # noqa: ARG001
         return []
@@ -140,7 +145,7 @@ def typed_notify(value: int) -> None:  # noqa: ARG001
         return None
 
     default_list_slot = slot(collect_list)
-    list_slot = slot(collect_list, unique=True)
+    list_slot = slot(collect_list, unique=True, explicit_plugin_names=True)
     signature_list_slot = slot(collect_list, signature=['.'])
     dict_slot = slot(collect_dict, signature='.', name='collect', max=2, type_check=False, entrypoint_group='custom', unique=True)
     signature_list_dict_slot = slot(collect_dict, signature=['.'])
@@ -400,7 +405,7 @@ def collect(value: int) -> List[int]:  # noqa: ARG001
 
 
 @pytest.mark.mypy_testing
-def test_slot_bad_factory_arguments_stay_type_errors():
+def test_slot_bad_factory_arguments_include_explicit_plugin_names_type_errors():
     """Pin invalid slot(...) calls via code-specific expectations.
 
     Calls producing bundled overload diagnostics use targeted ignores together
@@ -417,11 +422,13 @@ def test_slot_bad_factory_arguments_stay_type_errors():
     slot(type_check='yes')  # type: ignore[call-overload]
     slot(entrypoint_group=None)  # type: ignore[call-overload]
     slot(unique='yes')  # type: ignore[call-overload]
+    slot(explicit_plugin_names='yes')  # type: ignore[call-overload]
 
     def collect(value: int) -> List[int]:  # noqa: ARG001
         return []
 
     slot(collect, unique='yes')  # type: ignore[call-overload]
+    slot(collect, explicit_plugin_names='yes')  # type: ignore[call-overload]
     with pytest.raises(TypeError):
         slot(collect, signature=[1])  # E: [list-item]
     with pytest.raises(TypeError):