Skip to content

feat: expose FixtureFunctionDefinition for typing #14862

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
teddygood wants to merge 1 commit into
base: main
Choose a base branch
from
+24 −1
Open

feat: expose FixtureFunctionDefinition for typing #14862

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AUTHORS
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@ Cal Leeming
Carl Friedrich Bolz
Carlos Jenkins
Ceridwen
Chanho Lee
Charles Cloud
Charles Machalow
Charles-Meldhine Madi Mnemoi (cmnemoi)
Expand Down
1 change: 1 addition & 0 deletions changelog/14853.feature.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Exposed :class:`pytest.FixtureFunctionDefinition` as the type of a fixture function after decoration by :func:`pytest.fixture`, allowing fixture factories to use it in type annotations.
1 change: 0 additions & 1 deletion doc/en/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,6 @@
("py:class", "_pytest._code.code.TerminalRepr"),
("py:class", "TerminalRepr"),
("py:class", "_pytest.fixtures.FixtureFunctionMarker"),
("py:class", "_pytest.fixtures.FixtureFunctionDefinition"),
("py:class", "_pytest.logging.LogCaptureHandler"),
("py:class", "_pytest.mark.structures.ParameterSet"),
# Intentionally undocumented/private
Expand Down
5 changes: 5 additions & 0 deletions doc/en/reference/reference.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1010,6 +1010,11 @@ FixtureDef
:members:
:show-inheritance:

FixtureFunctionDefinition
~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: pytest.FixtureFunctionDefinition()

MarkDecorator
~~~~~~~~~~~~~

Expand Down
6 changes: 6 additions & 0 deletions src/_pytest/fixtures.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1454,6 +1454,12 @@ def __call__(self, function: FixtureFunction) -> FixtureFunctionDefinition:

# TODO: paramspec/return type annotation tracking and storing
class FixtureFunctionDefinition:

@RonnyPfannschmidt RonnyPfannschmidt Aug 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pytest-dev/core if we expose this - do we want to make the return type a generic?

@teddygood teddygood Aug 15, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems directly related to the TODO introduced in #12473. I found #13036, which explored preserving both the ParamSpec and return type, and it was closed due to lack of time rather than because the design was rejected.
Since the generic arity and semantics would become part of the public API, I agree that this is worth settling before exposing the type. Do we want only a declared return-type parameter, or the ParamSpec plus return-type shape from #13036? For yield fixtures, should the type parameter represent the declared Generator[...] return type or the yielded fixture value?

I’ll wait for input from @pytest-dev/core before making further changes.

@nicoddemus nicoddemus Aug 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it makes sense to make the return type generic if possible.

@RonnyPfannschmidt RonnyPfannschmidt Aug 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems directly related to the TODO introduced in #12473. I found #13036, which explored preserving both the ParamSpec and return type, and it was closed due to lack of time rather than because the design was rejected. Since the generic arity and semantics would become part of the public API, I agree that this is worth settling before exposing the type. Do we want only a declared return-type parameter, or the ParamSpec plus return-type shape from #13036? For yield fixtures, should the type parameter represent the declared Generator[...] return type or the yielded fixture value?

I’ll wait for input from @pytest-dev/core before making further changes.

this seems quite a lot like a gpt driven rely - i think we may need to alter ai contribution policy a bit more as it increasingly difficult to distinguish good unattended model and attended model eagerly doing things on behalf of the user

@teddygood teddygood Aug 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

umm... I did use ai to help write the reply, but I reviewed it before posting. However, reading it again now, I can see that it sounds too ai assisted. sorry about that.

I found 13036 while looking into whether the return type should be generic, because it explored carrying the fixture function's parameter and return types through FixtureFunctionDefinition. That's where the ParamSpec question came from.

"""The type of a fixture function after decoration by :func:`pytest.fixture`.

This type is public for type annotations. It should not be instantiated

@bluetech bluetech Aug 20, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This paragraph isn't needed, we have runtime protection against this, so better to keep things short.

or subclassed by users, and its attributes are not part of the public API.

@The-Compiler The-Compiler Aug 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should probably be marked @final?

@teddygood teddygood Aug 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. I had considered whether @final was necessary, but you’re right. I’ll add it.

"""

def __init__(
self,
*,
Expand Down
2 changes: 2 additions & 0 deletions src/pytest/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
from _pytest.doctest import DoctestItem
from _pytest.fixtures import fixture
from _pytest.fixtures import FixtureDef
from _pytest.fixtures import FixtureFunctionDefinition
from _pytest.fixtures import FixtureLookupError
from _pytest.fixtures import FixtureRequest
from _pytest.fixtures import register_fixture
Expand Down Expand Up @@ -114,6 +115,7 @@
"ExitCode",
"File",
"FixtureDef",
"FixtureFunctionDefinition",
"FixtureLookupError",
"FixtureRequest",
"Function",
Expand Down
9 changes: 9 additions & 0 deletions testing/typing_checks.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,3 +78,12 @@ def check_scope_typing() -> None:
@pytest.mark.parametrize("x", [ImportError, AttributeError])
def check_mypy_bug_with_argvalues(x) -> None:
pass


# Issue #14853.
def check_fixture_factory(value: str) -> pytest.FixtureFunctionDefinition:
@pytest.fixture
def generated_fixture() -> str:
return value

return generated_fixture