[adoption] managed pytest config has no pass-through for pytest-asyncio ini settings, breaking subproject async tests

[chrisdpurcell]

Outcome

The managed pytest configuration exposes no closed option for pytest-asyncio settings (notably asyncio_mode), and the managed [tool.pytest.ini_options] at the root shadows a subproject's own pyproject configuration. A repository adopting python-tooling over a subproject with async tests fails its gate until tests are edited or an undocumented mechanism is found.

Evidence

• Fresh adoption, project-standards 5.26.0 (v5.26.0), Linux, Python 3.14.7.
• python-tooling 1.16 with pytest.test_paths = ["subproj/tests"]; the subproject's own pyproject.toml sets asyncio_mode = "auto" under its own [tool.pytest.ini_options].
• Under the root-managed config, pytest's rootdir is the repository root, so the subproject ini is not read; async tests fail with:

Failed: async def functions are not natively supported

The closed pytest options (fail_under, markers, coverage_exclude_also, test_paths) cannot express asyncio_mode, and [tool.pytest.ini_options] cannot be declared twice.

Expected behavior

Either a closed option to pass through pytest ini values (e.g. ini = { asyncio_mode = "auto" }), or adoption guidance stating that async tests must carry explicit pytest.mark.asyncio markers when adopted under a root-managed configuration, plus that the async plugin must be added via additional_dev_dependencies.

Workaround used

Added module-level pytestmark = pytest.mark.asyncio to the affected test modules (compatible with both asyncio modes) and pytest-asyncio through additional_dev_dependencies.

Blocks progress: no (workaround found).

[chrisdpurcell]

Investigation: the mechanism already exists and the requested option is an explicitly rejected design — but there is a real trap that makes the report's frustration justified

asyncio_mode is already consumer-owned; it does not need a new option

The KEY OWNERSHIP INVARIANT (issues #99 / #117, providers/python_tooling.py:270-282) states that this
package owns exactly the leaf keys it names, and that every undeclared key inside a table it contributes
to is consumer-owned by construction, not by an allow-list. _pytest_key (:479-486) shows the
owned set is exactly four keys:

"minversion": "9.0",
"testpaths": _test_paths(config),
"addopts": ["-ra", "--strict-markers", "--strict-config"],
"markers": _section(config, "pytest").get("markers"),

asyncio_mode is not among them, so a consumer can write it directly into the managed
[tool.pytest.ini_options] table and reconcile will preserve it. Contributions are identified per leaf
key (key:/tool/pytest/ini_options/<leaf>, :1029-1031), not per table, which is the mechanism that
makes this true. tests/package_contract/test_python_tooling_reconstruction.py:1693 demonstrates the
same preservation for a sibling undeclared key (pythonpath).

This resolves the report's stated blocker: [tool.pytest.ini_options] does not need to be declared
twice. The key is added to the existing table. That belief — reasonable, and stated explicitly in the
report — is what made the situation look unfixable.

The requested ini = { ... } pass-through is a considered rejection, not an oversight

The same comment block records it as a rejected alternative, with reasoning that applies verbatim here:

Rejected alternative: a bounded typed option per plugin ... or a generic sub-table passthrough. It
re-runs this defect for the next plugin a consumer adopts, imports Ruff's own schema into this
package's option surface where it cannot be validated, and still overwrites bytes a consumer wrote
directly. Adding a key here — not an option there — is how this package grows.

So the option the issue asks for is unlikely to be the right fix, and the report's alternative
proposal — adoption guidance — is the one that matches the package's design.

The genuine trap: the owned addopts carries --strict-config

This is the part I think deserves attention beyond documentation. The package owns
addopts = ["-ra", "--strict-markers", "--strict-config"]. --strict-config makes pytest error on
unrecognized ini keys. An ini key is only recognized when the plugin that registers it is installed.

Consequently the consumer-owned escape hatch is conditional in a way nothing documents: writing
asyncio_mode = "auto" into the managed table works only if pytest-asyncio is already installed, and
otherwise converts a clear async def functions are not natively supported failure into a config error
about an unknown key. The adopter must do two things in the right order — add the plugin through
additional_dev_dependencies, then set the key — and the package owns the flag that makes the wrong
order fail confusingly.

The reporter independently arrived at the plugin half of this (they added pytest-asyncio via
additional_dev_dependencies), which supports the reading that the ordering constraint is discoverable
only by trial.

The rootdir claim in the report is correct

Under a root-managed [tool.pytest.ini_options], pytest's rootdir/ini discovery stops at the first ini
file it finds, so a subproject's own [tool.pytest.ini_options] is genuinely not read. That is inherent
to pytest, not to this package, but it is the reason the consumer-owned-key route is the only one
available.

Suggested shape of a fix (for triage, not a decision)

1. A troubleshooting row stating that undeclared keys in [tool.pytest.ini_options] are consumer-owned
   and may be written directly — this single fact resolves the report and is currently absent from the
   adopter-facing documentation, living only in a provider source comment.
2. In the same row, name the --strict-config ordering constraint explicitly: install the plugin via
   additional_dev_dependencies first, then add its ini key.
3. Keep the closed-option surface as is, per the rejected-alternative reasoning above.

Version status

All references are 1.17 (shipping in v5.27.0); behavior is unchanged from the reported 1.16. A fix lands
in 1.18 — 1.17's payload bytes freeze at the v5.27.0 tag.

Evidence gathered read-only against the working tree; nothing here touched the in-flight release.

[chrisdpurcell]

Fields set under the operator's 2026-09-01 instruction: Type=Bug, Workflow=Ready, Priority=P2 Planned, Size=S, Change risk=R1 Low, Execution mode=Unattended agent.

The fix lands in python-tooling 1.18 for release v5.28.0.

Acceptance criteria (authored 2026-09-01 by the session orchestrator from the owner's investigation comment):

1. adopt.md's troubleshooting table gains a row stating undeclared [tool.pytest.ini_options] keys (e.g. asyncio_mode) are consumer-owned and may be written directly into the managed table.
2. The same row states the --strict-config ordering constraint — install the plugin via additional_dev_dependencies before adding its ini key, else a config error replaces the original failure.
3. No closed-option or generic-passthrough surface is added (per the rejected-alternative reasoning already on record).

[chrisdpurcell]

Resolved by python-tooling 1.18, cut in PR #225 (merged to testing as d08a79d, ships in v5.28.0). The acceptance criteria recorded on this issue are covered by the 1.18 adopt.md rows and the contract tests in tests/package_contract/test_python_tooling_1_18.py; the per-leaf-key preservation claim was additionally confirmed end-to-end in a live consumer repro this session (keys survive reconcile --apply, validate, and an option change that rewrites the same table). 1.17 stays byte-immutable.