How to force blank line after function docstring (D202)

[CarrotManMatt]

Rule D202 prevents any blank lines after function docstrings, however I find it easier to read when a single blank line is there. Similar to choosing D211/D203 is there a rule or configuration I could change to enforce a single blank line (rather than just turning the rule off)

X-Posted to Discord help channel forum (https://discord.com/channels/1039017663004942429/1149497948363825302)

[lelit]

I briefly tried to use the pydocstyle formatter, and even explicitly using the pep257 convention it removes the empty line between the docstring and body of a function, while it enforces an empty string between a class docstring and class attributes.

I see this has been closed as outdated, but I could not find any solution: is it still impossible to opt for a different behaviour?

My .toml.ruff:

[lint.pydocstyle]
convention = "pep257"

Sample Python source:

"""
This is a top-level docstring.

It explains what the module does.
"""


class Class:
    """
    This is the docstring of a specific class.

    It explains the purpose of the class, and introduces it significant entry-points.
    """

    CONST: int = 0
    """
    This is the docstring of a class attribute.
    """

    def method(self) -> None:
        """
        This is the docstring of a method of the class.

        It should tell what the method does, list its arguments and their meaning.
        """

        return None


def function(a: int, b: str) -> str:
    """
    This is the docstring for a function.

    It should mention `a` and `b` and tell that it returns their multiplication.
    """

    return b * a

Output of ruff check --diff --select D:

--- foo.py
+++ foo.py
@@ -23,7 +23,6 @@
 
         It should tell what the method does, list its arguments and their meaning.
         """
-
         return None
 
 
@@ -33,5 +32,4 @@
 
     It should mention `a` and `b` and tell that it returns their multiplication.
     """
-
     return b * a

Would fix 2 errors.

[MichaReiser]

You can explicitly disable D202 using ignore if you dont' want that specific rule enforced. However, it doesn't give you the opposite of enforcing that there's always one empty line after the function docstring

[lelit]

Uhm, I tried adding that to .ruff.toml:

[lint]
ignore = ["D202"]

[lint.pydocstyle]
convention = "pep257"

but I still get

foo.py:21:9: D202 [*] No blank lines allowed after function docstring (found 1)
   |
20 |       def method(self) -> None:
21 |           """
   |  _________^
22 | |         This is the docstring of a method of the class.
23 | | 
24 | |         It should tell what the method does, list its arguments and their meaning.
25 | |         """
   | |___________^ D202
26 |   
27 |           return None
   |
   = help: Remove blank line(s) after function docstring
...

[MichaReiser]

Hmm, this should work. I just tried to reproduce this locally with (arguably a pyproject.toml but that shouldn't change anything)

[tool.ruff.lint]
select = ["E402", "D"]
ignore = ["D202"]


[tool.ruff.lint.pydocstyle]
convention = "pep257"

"""
This is a top-level docstring.

It explains what the module does.
"""


class Class:
    """
    This is the docstring of a specific class.

    It explains the purpose of the class, and introduces it significant entry-points.
    """

    CONST: int = 0
    """
    This is the docstring of a class attribute.
    """

    def method(self) -> None:
        """
        This is the docstring of a method of the class.

        It should tell what the method does, list its arguments and their meaning.
        """

        return None


def function(a: int, b: str) -> str:
    """
    This is the docstring for a function.

    It should mention `a` and `b` and tell that it returns their multiplication.
    """

    return b * a

Commenting out the `ignore = ["D202"] makes the violation appear.

Can you try running ruff check --show-settings to see the resolved settings? And maybe try ruff check --verbose to see which configuration files Ruff's picks up

[lelit]

Ah, got it: for some reason, specifying --select D on the command line has is stronger than specifying that in the .ruff.toml: above ran ruff check --select D, but if I omit the --select option and put it in the config file instead, as

[lint]
select = ["D"]
ignore = ["D202"]

[lint.pydocstyle]
convention = "pep257"

then it works as expected.

[MichaReiser]

That's great to hear. You may want to use extend-select unless it is intentional to override the enabled-by-default rules.