refactor: dispatch config file loading by filename, then suffix

[RonnyPfannschmidt]

Supersedes #8358, #14707, #14723, #14671, #14454 and #14579.

Closes #14705
Closes #14716
Closes #11502
Closes #13246
Closes #9703

Three commits: a behaviour-preserving refactor of config file dispatch, then the fixes it makes small, then the rootdir fix. Review them separately — the first is intended to be a pure refactor; the second and third deliberately change behaviour (including one breaking change, flagged below).

Commit 1: refactor config file dispatch

Re-does the structural part of #8358 on top of current main. That PR bundled the refactor with the setup.cfg deprecation from #3523; the deprecation was abandoned (and reverted within the branch), and the refactor — which @nicoddemus had signed off as "Overall the changes look good" — went down with it. This PR carries only the structural change. No deprecation, no policy change, no behaviour change.

It can't be cherry-picked: the 2021 branch predates ConfigValue, native TOML mode, ini option aliases, pytest.toml/.pytest.toml, and ignored_config_files. So this is a re-implementation of the same design against today's code.

The problem

Knowledge about config files is currently spread across three places that must be kept in sync by hand:

1. load_config_dict_from_file dispatches on suffix (if filepath.suffix == ".ini" / elif ".cfg" / elif ".toml"), with filename checks nested inside those branches (if filepath.name in {"pytest.ini", ".pytest.ini"}, if filepath.name in ("pytest.toml", ".pytest.toml")).
2. locate_config re-declares the discovery order in a separate hardcoded config_names list.
3. Adding a format means touching both, in the right order, plus the nested name checks.

The name-vs-suffix distinction is real and load-bearing — pytest.ini is config even when empty, a random .ini is not; pyproject.toml reads [tool.pytest], pytest.toml reads [pytest] — but it is implicit and interleaved rather than expressed.

The change

Two tables, and dispatch that reads off them:

CONFIG_LOADERS = {          # by name; also *is* the discovery order
    "pytest.toml":   _parse_pytest_toml,
    ".pytest.toml":  _parse_pytest_toml,
    "pytest.ini":    _parse_pytest_ini,
    ".pytest.ini":   _parse_pytest_ini,
    "pyproject.toml": _parse_pyproject_toml,
    "tox.ini":       _parse_ini_file,
    "setup.cfg":     _parse_cfg_file,
}

CONFIG_SUFFIXES = {         # by suffix; for arbitrary files passed via -c
    ".ini":  _parse_ini_file,
    ".cfg":  _parse_cfg_file,
    ".toml": _parse_pyproject_toml,   # what main does today; commit 2 changes this
}

def load_config_dict_from_file(filepath):
    loader = CONFIG_LOADERS.get(filepath.name) or CONFIG_SUFFIXES.get(filepath.suffix)
    return loader(filepath) if loader is not None else None

locate_config now iterates CONFIG_LOADERS directly instead of maintaining its own list, so discovery order and parsing can no longer drift apart.

Per-format semantics move into named functions — _parse_pytest_ini, _parse_ini_file, _parse_cfg_file, _parse_pytest_toml, _parse_pyproject_toml — each with a docstring stating its rule, instead of living in nested conditionals inside one ~100-line function.

Behaviour preservation

This is intended to be a pure refactor.

• Full test suite passes unchanged; no test needed modifying.
• Additionally, I ran load_config_dict_from_file over a 38-case matrix (every supported name × present/absent/empty/malformed section, plus .txt and extension-less files) under main and under this branch, comparing returned values, ConfigValue.mode/origin, and raised exception types and messages. Output is byte-identical.

Two spots deliberately keep a pre-existing wart rather than quietly fixing it, so the diff stays behaviour-preserving:

• _parse_cfg_file still hardcodes setup.cfg in the CFG_PYTEST_SECTION message even for other .cfg files.
• _parse_pytest_toml/_parse_pyproject_toml still assume the pytest key is a table; a scalar there raises AttributeError as before (hence the type: ignore comments). Worth hardening, separately.

In this commit CONFIG_SUFFIXES[".toml"] still points at _parse_pyproject_toml, which is what main does today, so that the refactor decides nothing. Commit 2 changes it — that is #14705.

Why now

Three open PRs are each adding another special case to exactly the conditionals this removes, and two of them conflict:

• Fix custom TOML config files passed with -c #14707 (custom TOML via -c) is the name-vs-suffix confusion itself. On this branch it becomes a one-line change — point CONFIG_SUFFIXES[".toml"] at a _parse_pytest_toml-style loader — with no risk to pyproject.toml discovery. As currently written it inverts a nested check to filepath.name != "pyproject.toml", i.e. dispatch by negation.
• fix: validate explicit config file paths #14723 introduces SUPPORTED_CONFIG_FILE_EXTENSIONS — a fourth hardcoded table of file knowledge. Here that set is CONFIG_SUFFIXES.keys(), derived rather than declared.
• fix: validate explicit config file paths #14723 and Do not derive rootdir from a non-regular config file #14671 edit the same determine_setup branch in opposite directions: fix: validate explicit config file paths #14723 rejects any config path where is_file() is false, Do not derive rootdir from a non-regular config file #14671 exists to support --config-file=/dev/null (a character device, so is_file() is false). Whichever lands second silently undoes the other.

Landing this first turns those three into small, independent, non-conflicting changes — which is what commit 2 does.

---

Commit 2: the three fixes the refactor enables

fix: validate -c/--config-file and read [pytest] from custom TOML files

Consolidates three open reports that all bottom out in how an explicitly given config file is located and parsed:

Issue	Fix	Size
#14705 — custom TOML reads [tool.pytest] instead of [pytest]	CONFIG_SUFFIXES[".toml"] now points at _parse_pytest_toml	one table entry
#14716 — -c has two failure modes for invalid paths	determine_setup rejects nonexistent paths, directories, and regular files with no loader	supported extensions derived from CONFIG_SUFFIXES
#11502 — --config-file=/dev/null gives rootdir: /dev	non-regular config file → empty config, rootdir falls back to common ancestor	conditional on is_file()

The diagnoses come from #14707 (@DebadityaHait), #14723 (@wanxiankai) and #14671 (@apoorvdarshan) — this PR supersedes all three, with smaller implementations because the dispatch tables carry the file knowledge.

Notably #14723 and #14671 are mutually exclusive as written: #14723 rejects any config path where is_file() is false, while #14671 exists to support --config-file=/dev/null, a character device for which is_file() is false. Splitting the check into exists (error if not) and is a regular file (parse it, and only then derive the rootdir from it) satisfies both.

⚠️ Breaking

Passing a file pytest has no loader for to -c/--config-file is now a UsageError instead of being silently ignored. pytest's own #14683 regression test did this with a conftest.py; it now uses a real config file, and since it passes --rootdir explicitly the config file was incidental to what it covers.

Verification

Full suite green (4337 passed, 47 skipped, 13 xfailed, 7 xpassed — the xpasses are pre-existing, #11603/#10042). Each reported reproducer checked by hand as well: the custom-TOML case is confirmed by python_files from the custom file actually taking effect, and the /dev/null case by the rootdir landing on the project directory with no PytestCacheWarning.

---

Commit 3: the config file's directory no longer decides the rootdir alone

-c set the rootdir to the config file's parent. With the common -c config/pytest.ini layout that moved the rootdir into config/, so conftests collected an empty path prefix: same-named fixtures from sibling directories shadowed each other and node ids came out as config::test2 rather than tests/tests2/test2.py::test2.

The config file's location is evidence about where the project lives, not a decision on its own. Take the common ancestor of the config file's directory and the collected test paths, using the invocation directory in their place when no paths were given. If the two live in unrelated trees the ancestor degrades to the filesystem root, in which case the config file's directory is kept, as today.

scenario	before	#14454	#14579	this PR
-c config/pytest.ini (no args)	config/	✅	config/	✅
-c config/pytest.ini tests/	config/	✅	✅	✅
sibling config, invoked from a subdirectory	config/	sub/	✅	✅
unrelated working directory	config/	unrelated dir	✅	✅

This supersedes both open proposals:

• determine_setup: use invocation_dir as rootdir when -c is given #14454 (@EternalRights) found the root cause and drove the design discussion. Its invocation_dir rule is right for the no-args case but follows the working directory even when that is unrelated to the project. Its ambiguity warning is also written to Parser.extra_info, which is only rendered by PytestArgumentParser.error() — so it never appears on a successful run, and its tests pass by asserting on config._parser.extra_info directly.
• Fix rootdir with explicit config and test paths #14579 (@hariharan077) contributed the common-ancestor form, which is most of the answer, but special-cases if dirs and so leaves the no-args case unfixed.

No ambiguity warning is needed once the ancestor also considers the invocation directory, because the rootdir is then derived rather than guessed.

Verified against the original reproducers by swapping in main's findpaths.py and running the same commands: on main the #13246 repro gives FAILED config::test2 - assert 1 == 2 and rootdir: .../config; with this commit, 2 passed and rootdir: .../ — the project root.

⚠️ Behaviour change beyond a plain bugfix: running from a subdirectory with a sibling config directory now roots at their common ancestor rather than at the config directory.