search

astral-sh / ruff

An extremely fast Python linter and code formatter, written in Rust.
https://docs.astral.sh/ruff
MIT License
30.97k stars 1.03k forks source link

docstring-missing-returns (`DOC201`) reports on pytest fixtures #13143

Open tjkuson opened 2 weeks ago

tjkuson commented 2 weeks ago

Running ruff check --select DOC201 --preview --isolated (Ruff version 0.6.2) on

import pytest

@pytest.fixture
def foo() -> int:
    """A very helpful docstring."""
    return 1

reports a docstring-missing-returns (DOC201) diagnostic.

The expected behaviour is that the return value of a function decorated with pytest.fixture is not expected to be documented, as such objects are not expected to be called by the user.

Search terms: DOC201, docstring-missing-returns, pydoclint, pytest, fixture

AlexWaygood commented 2 weeks ago

I don't know about this. I agree that it doesn't really make sense to enforce the usual set of docstring rules on, well, any test functions. But I'm not sure that I like the idea of special-casing specific third-party libraries for this kind of rule (even very popular libraries like pytest). My usual approach is just to set per-file-ignores in my Ruff config so that all docstring-related rules are ignored for my test files.

tjkuson commented 2 weeks ago

That's a fair point. Ignoring the rule would be a solution, though there are some functions in test files over which I would still want to run pydoclint checks (for example, complex mocks and utility functions).

MichaReiser commented 1 week ago

That's a fair point. Ignoring the rule would be a solution, though there are some functions in test files over which I would still want to run pydoclint checks (for example, complex mocks and utility functions).

It sounds difficult for an automated tool to decide for which functions pydoclint should run if only some functions should be checked. I guess my recommendation would be to move these utility functions to a different directory that still gets checked.