Pylint and ruff don't complain about useless (unnecessary) return in functions with docstring

Question

In pylint docs we read:

Emitted when a single "return" or "return None" statement is found at the end of function or method definition. This statement can safely be removed because Python will implicitly return None

In ruff docs on PLR1711 we read:

What it does

Checks for functions that end with an unnecessary return or return None, and contain no other return statements.

Sounds like in ruff's documentation unnecessary return or return None refers to such statement with removal of which the function would stay practically the same.

So both ruff and pylint should flag this return, right?:

def f():
    """docs"""
    return None

But they don't. I ran this in fresh google colab environment:

!pip install pylint ruff>/dev/null
!pylint --version && ruff --version
!printf "\nDOCS :\n"
!printf 'def f():\n    """docs"""\n    return None' > a.py
!pylint --disable C a.py
!ruff check --extend-select PLR1711 a.py
!printf "\nPRINT :\n"
!printf 'def f():\n    print()\n    return None' > a.py
!pylint --disable C a.py
!ruff check --extend-select PLR1711 a.py

and got:

pylint 3.3.1
astroid 3.3.5
Python 3.10.12 (main, Sep 11 2024, 15:47:36) [GCC 11.4.0]
ruff 0.7.4

DOCS :

------------------------------------
Your code has been rated at 10.00/10

All checks passed!

PRINT :
************* Module a
a.py:1:0: R1711: Useless return at end of function or method (useless-return)

-------------------------------------------------------------------
Your code has been rated at 6.67/10 (previous run: 10.00/10, -3.33)

a.py:3:5: PLR1711 [*] Useless `return` statement at end of function
  |
1 | def f():
2 |     print()
3 |     return None
  |     ^^^^^^^^^^^ PLR1711
  |
  = help: Remove useless `return` statement

Found 1 error.
[*] 1 fixable with the `--fix` option.

So can we get these tools to complain about such returns?

Answer 1

The exact logic that Ruff uses to check for PLR1711 "useless return statement" is spelled out in useless_return.rs, complete with detailed comments that explain each check.

In this case, it looks like Ruff (and possibly PyLint) has special exceptions for (a) functions that consist solely of a return statement, and (b) functions that consist solely of a docstring plus a return statement.

Case (a) is fairly obvious; a function needs a body, and pass is rather less explicit (and less intuitive) than return None. Case (b) is an extension of case (a): the presence (or absence) of a docstring should not normally affect how a function is interpreted, and a function that contains only a docstring will look rather unfinished, whereas a function that contains an explicit return None makes it clearer that this is intended behaviour.

Keep in mind that lint rules are typically intended to be pragmatic, rather than absolute. This is why exceptions to the rules exist. It may be the case that the documentation needs to be updated, which would be a perfectly reasonable thing to ask for.

If the lint logic bothers you, you are welcome to build your own checks (actually not hard, using the ast module), or fork an existing linter and modify the rules to taste.