feat(decorators): attach Hook*Configuration objects on marked functions

Complete design step 03: markers already attach configuration objects
since step 02; this finishes the step by storing the spec configuration
as HookSpec.config (try-claude naming) with a deprecated .opts alias,
reading .config in HookCaller firstresult resolution, and covering
decoration-time historic+firstresult validation and configuration
attachment with tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: RonnyPfannschmidt

changelog/705.trivial.rst

@@ -0,0 +1,3 @@
+``HookSpec`` now stores its :class:`pluggy.HookspecConfiguration` as
+``config``; the old ``opts`` attribute remains as a deprecated alias
+property.

src/pluggy/_caller.py

@@ -183,7 +183,7 @@ def __call__(self, **kwargs: object) -> Any:
             "Cannot directly call a historic hook - use call_historic instead."
         )
         self._verify_all_args_are_provided(kwargs)
-        firstresult = self.spec.opts.firstresult if self.spec else False
+        firstresult = self.spec.config.firstresult if self.spec else False
         # Copy because plugins may register other plugins during iteration (#438).
         return self._hookexec(self.name, self._hookimpls.copy(), kwargs, firstresult)
 
@@ -238,7 +238,7 @@ def call_extra(
             ):
                 i -= 1
             hookimpls.insert(i + 1, hookimpl)
-        firstresult = self.spec.opts.firstresult if self.spec else False
+        firstresult = self.spec.config.firstresult if self.spec else False
         return self._hookexec(self.name, hookimpls, kwargs, firstresult)
 
     def _maybe_apply_history(self, method: HookImpl) -> None:

src/pluggy/_decorators.py

@@ -332,13 +332,13 @@ class HookSpec:
         "name",
         "argnames",
         "kwargnames",
-        "opts",
+        "config",
         "warn_on_impl",
         "warn_on_impl_args",
     )
 
     def __init__(
-        self, namespace: _Namespace, name: str, opts: HookspecConfiguration
+        self, namespace: _Namespace, name: str, config: HookspecConfiguration
     ) -> None:
         self.namespace = namespace
         self.name = name
@@ -349,6 +349,15 @@ def __init__(
         self.argnames, self.kwargnames = varnames(
             self.function, legacy_noself=legacy_noself
         )
-        self.opts = opts
-        self.warn_on_impl = opts.warn_on_impl
-        self.warn_on_impl_args = opts.warn_on_impl_args
+        self.config = config
+        self.warn_on_impl = config.warn_on_impl
+        self.warn_on_impl_args = config.warn_on_impl_args
+
+    @property
+    def opts(self) -> HookspecConfiguration:
+        """Alias for :attr:`config`.
+
+        .. deprecated::
+            Use :attr:`config` instead.
+        """
+        return self.config

testing/test_configuration.py

@@ -222,6 +222,34 @@ def myimpl(arg: object) -> str:
     assert impl_config.tryfirst is True
 
 
+def test_historic_firstresult_raises_at_decoration_time() -> None:
+    hookspec = HookspecMarker("test")
+
+    with pytest.raises(ValueError, match="cannot have a historic firstresult"):
+
+        @hookspec(historic=True, firstresult=True)
+        def myspec() -> None:
+            pass
+
+
+def test_hookspec_stores_configuration() -> None:
+    pm = PluginManager("test")
+    hookspec = HookspecMarker("test")
+
+    class Spec:
+        @hookspec(firstresult=True)
+        def myhook(self, arg: object) -> None:
+            pass
+
+    pm.add_hookspecs(Spec)
+    spec = pm.hook.myhook.spec
+    assert spec is not None
+    assert isinstance(spec.config, HookspecConfiguration)
+    assert spec.config.firstresult is True
+    # Deprecated alias.
+    assert spec.opts is spec.config
+
+
 def test_config_integration_with_hooks() -> None:
     pm = PluginManager("test")
     hookspec = HookspecMarker("test")

testing/test_hookcaller.py

@@ -317,11 +317,11 @@ def he_myhook3(self, arg1) -> None:
 
     pm.add_hookspecs(HookSpec)
     assert pm.hook.he_myhook1.spec is not None
-    assert not pm.hook.he_myhook1.spec.opts.firstresult
+    assert not pm.hook.he_myhook1.spec.config.firstresult
     assert pm.hook.he_myhook2.spec is not None
-    assert pm.hook.he_myhook2.spec.opts.firstresult
+    assert pm.hook.he_myhook2.spec.config.firstresult
     assert pm.hook.he_myhook3.spec is not None
-    assert not pm.hook.he_myhook3.spec.opts.firstresult
+    assert not pm.hook.he_myhook3.spec.config.firstresult
 
 
 @pytest.mark.parametrize("name", ["hookwrapper", "optionalhook", "tryfirst", "trylast"])