pytest public API boundary ambiguity causes silent plugin breakage on minor upgrades

Direct Answer

There is no machine-readable manifest or versioned contract that definitively distinguishes pytest's guaranteed-public symbols from internal re-exports. The project relies on informal stability: symbols documented in the official reference are treated as stable, while undocumented or changelog-noted re-exports may break without notice across minor versions.

Confirmed Facts

• pytest.__all__ contains the current public surface, but this list evolves without semantic versioning guarantees for individual symbols.
• Symbols like FixtureRequest, Parser, and HookspecMarker are re-exported at the top level but are not marked as provisional or stable in documentation.
• The py.typed marker exists in the package, but type hints do not indicate stability levels (e.g., no @deprecated or @provisional decorators).
• Plugin breakage from minor upgrades is typically detected only through test failures or import errors after the fact.

Recommended Workflow

1. Limit imports to documented symbols: Only use symbols listed in the official pytest API reference (https://docs.pytest.org/en/stable/reference/reference.html) as stable. Avoid importing from pytest root unless the symbol is explicitly documented.
2. Run tests across consecutive minor versions: Before releasing a plugin, test against both the current version and the next minor version (e.g., 8.3 and 8.4) to catch silent breakage early.
3. Pin and monitor: Pin pytest in requirements.txt or pyproject.toml and subscribe to changelog notifications. The pytest changelog explicitly notes when symbols are removed or moved.
4. Use explicit submodule imports: Where possible, import from internal modules (e.g., _pytest.fixtures) with awareness that these are internal APIs with no stability guarantee.

On a Formal API Layer

Adopting a pluggy-style hookspec layer for the public API would require deliberate project-level changes. Such a layer would need:

• A clear separation between public plugin interfaces and internal implementation.
• Versioned contracts for each public symbol or group of symbols.
• Deprecation cycles with FutureWarning or DeprecationWarning before removal.

This does not exist in pytest today. Any plugin seeking long-term stability should minimize reliance on top-level re-exports and monitor the changelog closely.

Verification Steps

• Run python -c "import pytest; print([x for x in dir(pytest) if not x.startswith('_')])" to list all public names.
• Cross-reference this list with the latest pytest API reference documentation.
• Check pytest/__init__.pyi (if present) or pytest/__init__.py for __all__ definition.