Black should have an opinion about empty line after functions doc string

[erdnaxeli]

Currently Black forces an empty line after a class docstring, but it does not do it for functions.

This code will be left unchanged by Black:

def lol():
    """
    mdr
    """

    lol


def lol():
    """
    mdr
    """
    lol

Black should have an opinion about that. I don't really care about the choice.

[lithammer]

My gut feeling is the second approach (i.e. no blank line) is the most common style (even Black itself is using it). All examples in PEP 257 use it as well, this is also mentioned under "One-line Docstrings":

There's no blank line either before or after the docstring.

[cas--]

Just to add, this SO answer referencing PEP 257 convinced me that there should be no space after docstring, except for class docstrings:

As pointed out by @moliware, the Docstring Conventions state, under One-line Docstrings:

There's no blank line either before or after the docstring.

HOWEVER, it also says (under Multi-line Docstrings):

Insert a blank line after all docstrings (one-line or multi-line) that document a class -- generally speaking, the class's methods are separated from each other by a single blank line, and the docstring needs to be offset from the first method by a blank line.

My interpretation of all this: blank lines should never precede any docstring, and should only follow a docstring when it is for a class.

So black should care about spaces after a docstring...

[wbolster]

to add to this, black currently adds a blank line below a class docstring, which i don't really care about in general, but for intentionally empty classes such as custom exceptions, it is good practice to add an explicit pass statement as the class body. this is not strictly needed from a syntactical point of view since the docstring itself is considered part of the class body by the python grammar, but it is a good idea to add it anyway to explicitly signal that this class is empty (as opposed to forgotten).

the problem is that black formats this as follows:

class MyCustomError(Exception):
    """My custom error."""

    pass

while it is arguably better to format it as

class MyCustomError(Exception):
    """My custom error."""
    pass

[JeremyLoy]

To track this issue against master, here is a link to the Black playground configured for this issue.

[ambv]

We will be tracking this in #450.