If I have the following file:

#!/usr/bin/env python3

Does this and

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

#!/usr/bin/env python3

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

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).

  • You mean "entire string"? Aug 3, 2015 at 11:45
  • 1
    This smells like a lot a bug. If no one comes up with a config variable for it, I think you should file a bug (even if someone answers with a work around).
    – Malabarba
    Aug 3, 2015 at 18:33
  • @Malabarba That is no bug. It formats the entire docstring according to the configured docstring style. That is expected behaviour! I forgot the name of the corresponding option, which is why I wrote no answer yet, but I wish that people wouldn't shout bug at any behaviour they don't immediately understand…
    – user227
    Aug 4, 2015 at 6:38

2 Answers 2


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))))
  • Until python-fill-paragraph is able to preserve at least the proper formatting of bullet points in the docstring, I think this really is an anti-feature.
    – Nikratio
    Aug 4, 2015 at 17:18
  • @Nikratio You're free to suggest improvements… or implement them.
    – user227
    Aug 4, 2015 at 17:21

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.