[PR #13529/40a1713d backport][8.4.x] docs: clarify comma-separated -p NAME,NAME2
limitations and recommend stable alternatives
#13532
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is a backport of PR #13529 as merged into main (40a1713).
Issue Body
Description
In the “Disabling plugins from autoloading” section, the docs show:
However, in practice this often fails with:
This happens both when that line is placed in
pytest.ini
(due to ConfigParser +shlex.split
behavior) and in Windows CMD/PowerShell (shell does not preserve the comma list as a single argument). Pytest ends up trying to import the entire comma-separated string as one module.Steps to Reproduce
Install pytest ≥8.4 and plugins
pytest-sugar
,pytest-xdist
.Create
pytest.ini
containing:Run in Windows CMD or PowerShell:
Observe the ImportError.
Actual Behavior
Expected Behavior
The doc’s example should note that a single
-p NAME,NAME2
is not reliably split into two plugin names when used inpytest.ini
or on Windows shells. Users need the following stable patterns:Suggested Documentation Update
Environment
pytest-sugar
,pytest-xdist
By calling out these parsing pitfalls and offering clear alternatives, the docs will better match real-world behavior and save users from this confusing import error.