PEP8 says
Note that most importantly, the """ that ends a multiline docstring
should be on a line by itself, and preferably preceded by a blank
line, e.g.:
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""
I find this rather bizarre, since it's just "extraneous whitespace" and treats opening quotations differently from closing quotations for no obvious reason.
A rationale is given is in PEP 257:
The BDFL recommends inserting a blank line between the last paragraph
in a multi-line docstring and its closing quotes, placing the closing
quotes on a line by themselves. This way, Emacs' fill-paragraph
command can be used on it.
Emacs, really? Everyone should do weird things to cater to the idiosyncrasies of a particular command in a particular editing tool?
I also think it's weird to put the beginning of the docstring on the same line as the quotes (not required, but recommended), while insisting that the closing quotations be on their own line. I think this is more logical, and should be used for both single line and multi-line docstrings:
def foobang(bizbaz, plotz=None):
"""
Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""
if plotz is not None:
...
Update: The bold part has been removed and now it just says to "place the closing quotes on a line by themselves", and that the "summary line may be on the same line as the opening quotes or on the next line".
