`pytest.hookimpl` does not respect the `specname` keyword argument

[seifertm]

Hook wrappers require the function name to start with the name of the hookspec, even when the specname keyword argument is passed to pytest.hookimpl.

Use case

I want to implement the same hook multiple times, once as a tryfirst hook and once as a wrapper. I cannot use the same function name in the same file, otherwise the second function overrides the first. I'm left with either putting the hookimpls into different modules or using the specname keyword argument which didn't work as expected.

The pytest docs about hooks link to pluggy and pytest exposes the pluggy hook interface. However, the pytest docs never mention the use of specname explicitly. Therefore, I'm not sure if this is a bug or if specname is not even intended to work in pytest. If this is the case, it would be helpful to receive an error, for example.

Minimal reproducer

The following setup is expected to print "Before hooks" and "After hooks" a couple of times when run with pytest -s.
It actually prints nothing and the hook implementation is silently ignored.

test_wrapper.py

def test_anything():
    pass

conftest.py

import pytest

@pytest.hookimpl(specname="pytest_pycollect_makeitem", hookwrapper=True)
# def pytest_pycollect_makeitem(collector, name, obj):  # works
# def pytest_pycollect_makeitem_abcd(collector, name, obj):  # works
def my_func_name(collector, name, obj):  # fails
    print("Before hooks")
    hook_result = yield
    print("After hooks")

Note that the specname keyword argument is not ignored. It raises and exception, when the specname does not correspond to a valid hookspec. However, the function name cannot be chosen freely even in presence of the specname kwarg. The function must always start with the name of the hookspec for the example to work.

Workaround

• Define hookimpls in different files
• Ensure that function names start with the name of the hook spec, i.e. pytest_pycollect_makeitemXYZ

Virtual environment

$ pip list
Package    Version
---------- -------
iniconfig  2.0.0
packaging  23.1
pip        23.2.1
pluggy     1.2.0
pytest     7.4.0
setuptools 68.0.0

[bluetech]

Thanks for the well-written issue.

This is due to this code in PytestPluginManager (a subclass of pluggy's PluginManager):

pytest/src/_pytest/config/__init__.py

Lines 443 to 448 in 556e075

	def parse_hookimpl_opts(self, plugin: _PluggyPlugin, name: str):
	# pytest hooks are always prefixed with "pytest_",
	# so we avoid accessing possibly non-readable attributes
	# (see issue #1073).
	if not name.startswith("pytest_"):
	return

So this is basically a tradeoff -- support specname or access possibly non-readable attributes. Unfortunately I think the latter is the bigger issue, and specname can't be supported properly (at least for names not beginning with pytest_) :( So one of your workarounds is needed.

We can switch to using safer attribute access i.e. getattr_static but that was very slow last time I checked and I don't think it's worth it.

[seifertm]

Thanks for the explanation! I don't understand the implications of a code change here, so I'm okay with whatever you decide in this matter.

I also found that the limitation about hooks having to start with pytest_ is documented in the Declaring new hooks section in the docs. I just didn't find it, because I wasn't trying to declare new hooks.

If an implementation change is not wanted, I'd suggest two documentation changes:

1. make the limitation about the pytest_ prefix and the specname kwarg more prominent in the docs, for example by adding a dedicated "limitations" section
2. Link to the limitations in the (otherwise excellent) example about hook ordering. The example currently insinuates that multiple hook implementations can be defined in a single file, which is not really the case.

Either of those adjustments would have saved me some debugging time.