feat(mark): expose `pytest.ParameterSet` in public API (#13431) by paneendrakumar0 · Pull Request #15193 · pytest-dev/pytest

paneendrakumar0 · 2026-10-16T08:48:39Z

Description

This PR addresses #13431 (part of the public API typing roadmap #7469) by exposing ParameterSet in the public pytest namespace as the return type of pytest.param().

Currently, developers using pytest.param in typed helper functions that return parameter sets receive private import warnings (such as Pyright's reportPrivateImportUsage) when importing ParameterSet from _pytest.mark.structures.

Summary of Changes

Public export: Exposed pytest.ParameterSet in src/pytest/__init__.py and included it in __all__.
Module declaration: Set __module__ = "pytest" on ParameterSet.
Private constructor: Refactored ParameterSet as a NamedTuple subclass with a __new__ constructor that calls check_ispytest(_ispytest) so direct instantiation issues a PytestDeprecationWarning, while internal factories (pytest.param(), extract_from(), etc.) instantiate with _ispytest=True.
Factory methods: Marked internal classmethods (param, extract_from) with :meta private: so Sphinx autodoc does not surface them under pytest.ParameterSet.
Documentation: Added pytest.ParameterSet to doc/en/reference/reference.rst under Objects, and removed the obsolete entry from nitpick_ignore in doc/en/conf.py.
Changelog: Added changelog/13431.improvement.rst.
Tests: Added comprehensive unit tests in testing/test_mark.py verifying public export, isinstance checking, deprecation warning on unflagged initialization, and pickle serialization.
Authors: Added myself to AUTHORS.

Closes #13431.

RonnyPfannschmidt

looks good, please add the extra documentation - the NOTSET followup is something we need to tinker a bit

RonnyPfannschmidt · 2026-10-17T07:33:26Z


-class ParameterSet(NamedTuple):
-    """A set of values for a set of parameters along with associated marks and
+class _ParameterSetBase(NamedTuple):


lets document hte minimal python version that makes this unnecessary for future cleanups

RonnyPfannschmidt · 2026-10-17T07:35:21Z

            parameters.append(
                ParameterSet(
-                    values=(NOTSET,) * len(argnames), marks=[mark], id="NOTSET"
+                    values=(NOTSET,) * len(argnames),


followup note - we might want to rethink this NOTSET hack - most recent python added sentinels and it muddles the types,

RonnyPfannschmidt · 2026-10-17T07:49:19Z

i jsut noted that i was wrong on a detail, i'm reassessing a bit more

RonnyPfannschmidt

🤖 Written by Claude Opus 5.5 via Claude Code for the pytest maintainers; I prompted it, it did the work, I read it.

Correcting my earlier review: my initial assessment was wrong. I'd like ParameterSet to be a completely public structure, not a private-constructor type.

Requested changes:

Drop _ispytest, the __new__/__reduce__ override and _ParameterSetBase. Go back to a plain class ParameterSet(NamedTuple). Direct construction has always worked (it was a plain NamedTuple), so the deprecation warning would be new breakage for existing users. Pickling works natively once __module__ points at pytest.
Type values as Sequence[object]. object | NotSetType collapses to object anyway, so the NotSetType part was only decorative.
Drop test_parameterset_direct_init_deprecated and keep the public-API and pickle tests.
That also resolves my line-85 comment: no Python version lifts the NamedTuple __new__/super() restriction (still a TypeError on 3.15), so there's no version to document once the split is gone.

I checked this locally on the PR head: mypy 2.4.0 and pyright 1.1.414 pass, and the full test suite passes.

One catch: mypy rejects __module__ = "pytest" inside a NamedTuple class body ("NamedTuple field name cannot start with an underscore"), so it has to be set after the class:

class ParameterSet(NamedTuple):
    ...

ParameterSet.__module__ = "pytest"

@bluetech, a detail I'd like your take on before we settle this:

Set __module__ after the class definition, as above. This is the minimal change, but it's the first public class done this way; everything else sets __module__ = "pytest" in the class body (approx, config, warning_types).
Put it in a public submodule of pytest so __module__ is naturally right. pytest currently has no public submodules, so this has its own rattail: a new import path we'd have to support (and that pickles would reference forever), docs and Sphinx paths, and import-cycle risk, since _pytest would import from pytest.* while pytest/__init__ imports _pytest.

My lean is option 1, since the rattail of option 2 seems larger than this type justifies. If we expect more NamedTuple/dataclass-style public types, though, it may be worth deciding the submodule question once.

The NOTSET placeholder for empty parameter sets stays as it is for now; I'll track that as a separate followup.

Generated by Claude Code

) Expose ParameterSet publicly from pytest as the return type of pytest.param() for type annotations and isinstance checks. - Re-export ParameterSet in src/pytest/__init__.py and include in __all__ - Keep ParameterSet as a plain NamedTuple with values: Sequence[object] - Set ParameterSet.__module__ = "pytest" after class definition - Mark internal factory methods with :meta private: for Sphinx autodoc - Document pytest.ParameterSet in doc/en/reference/reference.rst under Objects - Add changelog entry and unit tests for public API and pickle roundtrip

paneendrakumar0 · 2026-10-17T09:37:57Z

Thanks @RonnyPfannschmidt! Updated as requested:

Reverted ParameterSet to a plain NamedTuple without _ispytest or __new__/__reduce__ overrides.
Typed values: Sequence[object].
Set ParameterSet.__module__ = "pytest" after the class definition.
Dropped test_parameterset_direct_init_deprecated and verified direct instantiation alongside public API export and native pickling.
Full test suite and mypy pass cleanly.

for more information, see https://pre-commit.ci

RonnyPfannschmidt · 2026-10-17T10:04:55Z

Thanks im waiting for @bluetech 's assessment now

bluetech · 2026-10-18T13:01:59Z

+~~~~~~~~~~~~
+
+.. autoclass:: pytest.ParameterSet()
+    :members:


The members are undocumented and are shown as "Alias for field number 2" which is not so nice.

One of the fields has _HiddenParam type which is undocumented and errors out the docs build

Really I'm not sure we really want to document the members at this time. I guess it doesn't hurt but not essential since we only need it for typing purposes of the return value.

IOW, for now I'd just remove the :members:, which will fix the two issues I've pointed out.

bluetech · 2026-10-18T13:03:28Z


+    .. versionadded:: 9.2
+
    Examples::


The examples are too much for this public docstring, especially if we decide to hide the :members:. Maybe let's move it from the docstring to a code comment.

bluetech · 2026-10-18T13:05:10Z

        # ParameterSet(values=(40, 2, 42), marks=(), id="everything")
    """

-    values: Sequence[object | NotSetType]


What @RonnyPfannschmidt said about NotSetType being subsumed by object is correct, however the reason I did it is as a sort of documentation. It's meant to convey "this can be some value (any object allowed) or not set (NotSetType)". So I'd like to keep it, which should be OK if we hide :members:.

bluetech · 2026-10-18T13:05:39Z

    assert pytest.param(id=s)


+def test_parameterset_public_api() -> None:


This test seems not needed to me, I'd remove it.

bluetech · 2026-10-18T13:06:38Z

+    assert direct.id == "custom_id"
+
+
+def test_parameterset_pickle() -> None:


We don't usually test pickle-ability and I don't see a particular reason to start here... I'd remove this test.

bluetech · 2026-10-18T13:08:57Z

        return argnames, parameters


+ParameterSet.__module__ = "pytest"


I suppose a clarifying comment would be nice:

Suggested change

ParameterSet.__module__ = "pytest"

# mypy doesn't like `__module__` defined inline in the NamedTuple.

ParameterSet.__module__ = "pytest"

bluetech · 2026-10-18T13:10:03Z

+ParameterSet
+~~~~~~~~~~~~
+
+.. autoclass:: pytest.ParameterSet()


When defined like this the documentation doesn't show that this is a namedtuple. But that's fine for now, not sure we really want to promise this officially.

psf-chronographer Bot added the bot:chronographer:provided (automation) changelog entry is part of PR label Oct 16, 2026

paneendrakumar0 force-pushed the expose-parameterset-13431 branch from ab3cb09 to f03863b Compare October 16, 2026 09:20

RonnyPfannschmidt requested changes Oct 17, 2026

View reviewed changes

paneendrakumar0 force-pushed the expose-parameterset-13431 branch from f03863b to 9ae02e6 Compare October 17, 2026 09:37

pre-commit-ci Bot and others added 2 commits October 17, 2026 09:38

[pre-commit.ci] auto fixes from pre-commit.com hooks

49fd4ff

for more information, see https://pre-commit.ci

Merge branch 'main' into expose-parameterset-13431

e065b43

bluetech reviewed Oct 18, 2026

View reviewed changes

		assert pytest.param(id=s)


		def test_parameterset_public_api() -> None:

		assert direct.id == "custom_id"


		def test_parameterset_pickle() -> None:

		return argnames, parameters


		ParameterSet.__module__ = "pytest"

	ParameterSet.__module__ = "pytest"
	# mypy doesn't like `__module__` defined inline in the NamedTuple.
	ParameterSet.__module__ = "pytest"

Conversation

paneendrakumar0 commented Oct 16, 2026

Description

Summary of Changes

Uh oh!

RonnyPfannschmidt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RonnyPfannschmidt commented Oct 17, 2026

Uh oh!

RonnyPfannschmidt left a comment

Choose a reason for hiding this comment

Uh oh!

paneendrakumar0 commented Oct 17, 2026

Uh oh!

RonnyPfannschmidt commented Oct 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants