Proposals: import roots and packaged suites by RonnyPfannschmidt · Pull Request #10824 · pytest-dev/pytest

RonnyPfannschmidt · 2023-03-19T10:39:04Z

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.

This PR adds two design proposals under doc/en/proposals/. It contains no code. The goal is to agree on direction before any implementation PRs.

import_roots.rst: import roots. This is an opt-in, declarative alternative to --import-mode, configured in TOML. Each root states how part of the world maps onto the import system:

local: tests that aren't shipped. The convention is a top-level testing/ folder. Modules import under the root's required name, without any sys.path mutation.
mirrored: worktree source of an installed distribution, imported under its real name. Editable installs need no check, and a stale non-editable install fails collection.
installed: an installed distribution with no worktree involved, for example a test suite shipped inside a package.

Without roots configured, behaviour is unchanged. With roots configured, they replace --import-mode and pythonpath, and --pyargs resolves through them. Name collisions are hard errors, and there are no shims, aliases or implicit subprocess support.

packaged_suites.rst: packaged suites. A package can ship a test suite, for example a conformance suite for an interface, and declare its parameters in Python (SuiteSpec). A consuming project binds it from an initial conftest through a hook (pytest_bind_suites). Each binding becomes its own collector with scoped fixtures, so one suite can run against several implementations in one session. This replaces today's per-project workarounds: pandas and fsspec subclassing, SQLAlchemy's star-import plus setup.cfg sections, and array-api-tests' environment variable. A prototype plugin against main confirmed the collection, fixture scoping, parametrization and early validation behaviour. Packaged suites are independent of import roots and could land first.

Names in both documents are provisional. The packaged-suites naming deliberately avoids Test* names, which collection picks up, as well as unittest.TestSuite and junit-xml's "testsuite". It aligns with the *Spec vocabulary of the ensemble PoC (#14809).

Feedback wanted on:

the three root kinds and the TOML shape,
Python declaration plus hook binding for suites, versus alternatives such as fixture slots or TOML parameters,
names.

Related: #15022 (assertion rewriting of __init__.py under importlib mode, which a new finder would also hit), #14709 and #13257 (namespace shadowing that import roots aims to remove), #14809 (ensembles).

RonnyPfannschmidt · 2023-03-25T14:58:30Z

Note on implementation,

This will require py3.9+ importlib_metadata apis for the details on resource

An accompanying note to migrate to their apis seems necessary (so that pytest can warn on stale resources as well

The best way to register test root namespaces is still unclear

RonnyPfannschmidt · 2023-06-06T08:30:57Z

@bluetech i wonder if this proposal/idea could integrate with directory/package collection enhancements/changes in a way that allows migration

bluetech · 2023-06-06T09:30:11Z

+:orphan:
+
+===================================
+PROPOSAL: Parametrize with fixtures


Need to adjust this

bluetech · 2023-06-06T09:31:26Z

+test module discovery in pytest currently is is pre-pep40 and create pains for users
+by adding anything things to sys.path and creating easy conflicts in sys.modules


Suggested change

test module discovery in pytest currently is is pre-pep40 and create pains for users

by adding anything things to sys.path and creating easy conflicts in sys.modules

Test module discovery in pytest currently is is pre-PEP420 and creates pain for users

by adding things to ``sys.path`` and creating easy conflicts in ``sys.modules``.

bluetech · 2023-06-06T09:33:35Z

+A new import mode take a definition of import roots.
+
+a import root is either a folder in the worktree that will no be installed,
+or a folder that will be installed either normally or editable.


How is installation done? Like pytest will install to the venv with pip?

Users Will have to manage install, pytest should never do that part

bluetech · 2023-06-06T09:33:56Z

+
+In any case pytest will collect the file tree in the working directory.
+
+If normal install us used and the content of the imported file differs from the working directory,


Suggested change

If normal install us used and the content of the imported file differs from the working directory,

If normal install is used and the content of the imported file differs from the working directory,

gpshead · 2025-04-04T04:34:21Z

... any chance this proposal might happen? (I realize that's probably just asking if anyone is going to take on the work and I"m not here volunteering so... mostly just poking it to see if there is interest)

RonnyPfannschmidt · 2025-04-04T04:43:25Z

I have 2 refactoring of horror higher on my priority Lust ans im currently very thin stretched for time on that

nicoddemus · 2026-09-26T11:43:50Z

Read it and leaving a comment that this sounds like a step in the right direction. 👍

Rename the proposal from importmode_root_spec to import_roots and reposition it as a declarative alternative that replaces --import-mode instead of adding a fourth mode: * update the problem statement for the pytest 8 importlib rework (real module names, sys.modules insertion) and ground it in the modern import system (PEP 420/451/610/660, importlib.metadata) * specify implied roots for simple layouts with a hard failure on ambiguity instead of guessing * specify minimal editable vs real vs stale install classification via PEP 610 direct_url.json, with StaleInstallError on divergence * fix the copy-pasted title and turn the todo notes into a proper test case matrix Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Collection targets must map to exactly one root, testpaths entries act as an inference signal for local roots, and conftest files above every root are recorded as an open naming question. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Suites shipped inside installed packages declare their parameters in Python (SuiteSpec) and are bound by the consuming project's initial conftests via a hook (pytest_bind_suites). Names are provisional and chosen to avoid the Test* collection trap, unittest.TestSuite and the junit-xml testsuite meaning. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ae6NTCLoJgE5chCkbn19HX

Roots are opt-in (no behaviour change without them), TOML-only, with three kinds (local, mirrored, installed) and a required name. Local roots use declared names with a collision check and no sys.path, aliases or subprocess support. --pyargs resolves through roots; pythonpath is superseded. Implied roots are dropped. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ae6NTCLoJgE5chCkbn19HX

RonnyPfannschmidt force-pushed the draft-importmode-rootspec branch from a03a8fa to c37f550 Compare March 20, 2023 15:27

bluetech reviewed Jun 6, 2023

View reviewed changes

RonnyPfannschmidt mentioned this pull request Jul 26, 2023

Change how nodeids are created in relation to rootdir #11245

Open

Zac-HD mentioned this pull request Aug 9, 2023

Pytest Discovery broken when multiple modules have overlapping paths #11275

Open

RonnyPfannschmidt mentioned this pull request May 13, 2025

Fix: #13420 - Add cache for nodes._check_initialpaths_for_relpath #13422

Merged

The-Compiler force-pushed the main branch from cb2ee5b to ced9022 Compare July 24, 2026 09:22

RonnyPfannschmidt force-pushed the draft-importmode-rootspec branch from c37f550 to e690aff Compare July 24, 2026 09:38

RonnyPfannschmidt added the skip news used on prs to opt out of the changelog requirement label Jul 24, 2026

RonnyPfannschmidt force-pushed the draft-importmode-rootspec branch from e690aff to 25fc5d5 Compare September 15, 2026 11:34

RonnyPfannschmidt force-pushed the draft-importmode-rootspec branch from 25fc5d5 to 4523cda Compare September 23, 2026 07:00

RonnyPfannschmidt force-pushed the draft-importmode-rootspec branch from 4523cda to ae35c6f Compare October 4, 2026 13:06

RonnyPfannschmidt changed the title ~~Proposal: root spec import mode to replace legacy importing and importmode~~ Proposals: import roots and packaged suites Oct 6, 2026

RonnyPfannschmidt force-pushed the draft-importmode-rootspec branch from 20a48c5 to 238de34 Compare October 11, 2026 07:26

RonnyPfannschmidt and others added 5 commits October 14, 2026 22:10

WIP: throw together a initial halfassed proposal on rootspec import mode

1f64f95

RonnyPfannschmidt force-pushed the draft-importmode-rootspec branch from 238de34 to dddf9e7 Compare October 14, 2026 20:28

Navigation Menu

Repository navigation

Proposals: import roots and packaged suites - #10824

Proposals: import roots and packaged suites#10824
RonnyPfannschmidt wants to merge 5 commits into
pytest-dev:mainfrom
RonnyPfannschmidt:draft-importmode-rootspec

RonnyPfannschmidt commented Mar 19, 2023 •

edited

Loading

Uh oh!

RonnyPfannschmidt commented Mar 25, 2023

Uh oh!

RonnyPfannschmidt commented Jun 6, 2023

Uh oh!

bluetech Jun 6, 2023

Uh oh!

bluetech Jun 6, 2023

Uh oh!

bluetech Jun 6, 2023

Uh oh!

RonnyPfannschmidt Jun 6, 2023

Uh oh!

bluetech Jun 6, 2023

Uh oh!

gpshead commented Apr 4, 2025

Uh oh!

RonnyPfannschmidt commented Apr 4, 2025

Uh oh!

nicoddemus commented Sep 26, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

		test module discovery in pytest currently is is pre-pep40 and create pains for users
		by adding anything things to sys.path and creating easy conflicts in sys.modules


		In any case pytest will collect the file tree in the working directory.

		If normal install us used and the content of the imported file differs from the working directory,

	If normal install us used and the content of the imported file differs from the working directory,
	If normal install is used and the content of the imported file differs from the working directory,

Conversation

RonnyPfannschmidt commented Mar 19, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

RonnyPfannschmidt commented Mar 25, 2023

Uh oh!

RonnyPfannschmidt commented Jun 6, 2023

Uh oh!

bluetech Jun 6, 2023

Choose a reason for hiding this comment

Uh oh!

bluetech Jun 6, 2023

Choose a reason for hiding this comment

Uh oh!

bluetech Jun 6, 2023

Choose a reason for hiding this comment

Uh oh!

RonnyPfannschmidt Jun 6, 2023

Choose a reason for hiding this comment

Uh oh!

bluetech Jun 6, 2023

Choose a reason for hiding this comment

Uh oh!

gpshead commented Apr 4, 2025

Uh oh!

RonnyPfannschmidt commented Apr 4, 2025

Uh oh!

nicoddemus commented Sep 26, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

RonnyPfannschmidt commented Mar 19, 2023 •

edited

Loading