Let conftest.py skip its directory only with pytest.importorskip

[RonnyPfannschmidt]

Requested by Ronny · project thread

🤖 Written by Claude Opus 5.5 via Claude Code for the pytest maintainers; I prompted it, it did the work, I read it.

Closes #15142.

Before: a conftest.py with tables = pytest.importorskip("tables") skipped its directory under pytest, but pytest tests/io/pytables crashed with a raw Skipped traceback. A plain pytest.skip() in a conftest silently skipped the whole package, and pytest.fail() crashed the same way.

After: pytest.importorskip() in a conftest skips its directory however pytest is invoked, including node ids below it. pytest.skip() in a conftest, with or without allow_module_level=True, still skips but warns (PytestRemovedIn10Warning) and becomes an error in pytest 10. pytest.fail()/pytest.xfail() are reported as a conftest import error.

How

• New internal SkippedModule(Skipped) in _pytest.outcomes, raised by pytest.skip(allow_module_level=True), and its subclass SkippedImport, raised by pytest.importorskip() (including the minversion skip). Both set allow_module_level=True, so python.importtestmodule and anything reading the flag behave as before; their __qualname__ is Skipped, so reports are unchanged.
• _importconftest: SkippedImport propagates; any other Skipped warns first, then propagates; any other OutcomeException becomes ConftestImportFailure like other exceptions (cause is typed Exception | OutcomeException). The skip is cached per conftest, so the conftest runs once even when it is both an initial conftest and reached by collection.
• _set_initial_conftests leaves an anchor alone when a conftest on the way skips; the Dir collector re-raises the cached skip and reports it.
• Session.collect: a skipped collector on the way to an argument counts as matching it, so pytest test_mod.py::test_a into a module-level skip reports the skip instead of ERROR: found no collectors (applies to test modules too).
• --import-mode=importlib: _import_module_using_spec drops the module from sys.modules when executing it raises, like importlib does.

allow_module_level / SkippedModule assessment

Scan of 53k test files and conftests in 177 popular repos:

usage	calls	repos
importorskip at module top level	1297	76
skip(..., allow_module_level=True) at module top level	166	41
same, in a helper function called at import (e.g. numpy f2py)	6	5
same, in a package __init__.py	5	2
importorskip at conftest top level	10	6
skip(..., allow_module_level=True) in a conftest	0	0
explicit allow_module_level=False	0	0
reading .allow_module_level on an exception	0	0 (only pytest itself)
constructing Skipped(..., allow_module_level=...) directly	0	0

So the flag is only ever used as pytest.skip(..., allow_module_level=True), and nobody inspects it. That makes it a type in all but name; the subclasses let the conftest loader and importtestmodule ask isinstance() instead of reading an attribute. The allow_module_level parameter and attribute stay for compatibility.

Checklist

• Tests: TestConftestImportOutcome (test_conftest.py), node-id and SkippedModule/SkippedImport tests (test_skipping.py), importlib sys.modules test (test_pathlib.py). The new tests fail on main.
• Docs: how-to/skipping.rst "Skipping a whole directory", deprecations.rst entry.
• Changelog: 15142.bugfix.rst, 15142.deprecation.rst.
• AI agent credited in Co-authored-by trailer.

Full test suite passes locally (Python 3.13) apart from test_pdb_unittest_postmortem, a pexpect timing test that failed once and passed on 3 reruns; pre-commit run --all-files clean except zizmor, which needs GitHub API access not available here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GHmGPdXhVMcboqUeE6q62M