Make fill-paragraph in python-mode work on paragraph, not whole string

Question

If I have the following file:

#!/usr/bin/env python3
'''
bla.py

Does this and
that_
'''

..and call fill-paragraph with the cusor at _, then it acts on the entire docstring:

#!/usr/bin/env python3
'''bla.py

Does this and that_

'''

rather than just the second paragraph.

Is there a way to make it act on just the current paragraph, so that the result is:

#!/usr/bin/env python3
'''
bla.py

Does this and that_    
'''

(I know that I can select the second paragraph and then call fill-paragraph on the region, but I'd like it to work automatically on the current paragraph, not the current comment).

Answer 1

Python Mode provides its own fill-paragraph-function, called python-fill-paragraph. This function implements extensive formatting of code beyond just wrapping paragraphs.

Change the filling style

Notably, it formats docstrings according to python-fill-docstring-style, whose default value is pep-257, that is, formatting docstrings according to PEP 257 where the first sentence is one the same line with the opening quotes and a blank line is inserted before the closing quotes.

Your example shows a different docstring style. Change python-fill-docstring-style to django

(setq python-fill-docstring-style 'django)

which is the style used in your example. Python Mode will still fill the entire docstring, but preserve your style of writing docstrings.

This is the setting I’d recommend.

Really fill the paragraph only

Alternatively, you can tell Python Mode to fill only the current paragraph when in a comment, by customizing python-fill-string-function. This is the filling function that Python Mode uses when inside a string. The following setting makes Python Mode use the default filling behaviour in docstrings:

(setq python-fill-string-function (lambda (&optional justify region)
                                    (let ((fill-paragraph-function nil))
                                      (fill-paragraph justify region))))

Answer 2

I found that another solution is to set python-fill-docstring-style to nil.

Unfortunately this includes the triple quotes in the reformatting, so when reformatting the last paragraph in a docstring, the triple quotes end up on the same line.