17

I type a python docstring all on one line like this:

"""
This is a long docstring. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec a diam lectus. Sed sit amet ipsum mauris. Maecenas congue ligula ac quam viverra nec consectetur ante hendrerit. Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean ut gravida lorem. Ut turpis felis, pulvinar a semper sed, adipiscing id dolor. Pellentesque auctor nisi id magna consequat sagittis.
"""

and then I hit M-q (fill-paragraph), and I get this:

"""This is a long docstring. Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Donec a diam lectus. Sed sit amet ipsum
mauris. Maecenas congue ligula ac quam viverra nec consectetur ante
hendrerit. Donec et mollis dolor. Praesent et diam eget libero egestas
mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem
lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non
tortor. Lorem ipsum dolor sit amet, consectetur adipiscing
elit. Aenean ut gravida lorem. Ut turpis felis, pulvinar a semper sed,
adipiscing id dolor. Pellentesque auctor nisi id magna consequat
sagittis.

"""

I have two problems with this:

  1. The docstring starts on the same line as the """ -- I'd prefer to have the triple-quote stay on its own line.
  2. (Much lower priority.) The docstring ends with a blank line.

The example above is contrived, but I run into this frequently especially when editing existing docstrings where I'd like to simply M-q and have the whole para reflowed.

bstpierre
  • 280
  • 2
  • 10

2 Answers2

16

Customize python-fill-docstring-style accordingly, presuming that you are using the built-in Python Mode in Emacs 24.4. The default is pep-257, which leads to the style you observed, i.e. no newline at the beginning and two newlines before the end of a docstring.

Change this variable to symmetric or django to have Python Mode obey your preferred style, i.e. a newline at the beginning of the docstring, and a newline before the end:

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

Alternatively, set it via Directory Variables, to configure the docstring style individually per project.

symmetric and django are different w.r.t. single-line docstrings. The former puts the triple quotes on the same line if a docstring fits on one line, whereas the latter puts the triple quotes on separate lines in this case.

Take a look at the docstring of python-fill-docstring-style to see all available options.

  • PEP 257 does not mandate no newline at the beginning: "The summary line may be on the same line as the opening quotes or on the next line." I don't believe two newlines before the end is required either, since their example of a multi-line docstring doesn't use one. https://peps.python.org/pep-0257/#multi-line-docstrings – Noumenon Oct 06 '22 at 15:04
-1

W.r.t the empty line at the end, it looks like a plain bug, please report it with M-x report-emacs-bug. But for the first element, I'm not sure if it's a bug or a feature, so you might want to mention it in your bug report, but maybe the answer will be that it's just following the "PEP-NNN" convention.

This said, you might be able to fix the first problem with the following:

(add-hook 'python-mode-hook
          (lambda ()
            (set (make-local-variable 'paragraph-separate)
                 (concat paragraph-separate "\\|^[ \t]*\"\"\"[ \t]*$"))))
Stefan
  • 26,154
  • 3
  • 46
  • 84
  • 1
    It's neither a bug, nor should you need to change `paragraph-separate`. The docstring style of `python.el` is customizable. –  Oct 28 '14 at 13:32
  • Wow, I'd never have guessed that an extra empty line at the end of docstring could be something enforced by a standard. – Stefan Oct 28 '14 at 14:11
  • 1
    The standard (PEP 257) does not actually enforce this, it's just a (common) interpretation of it. Emacs also supports the variant without a trailing newline, as `pep-257-nn` in `python-fill-docstring-style`. –  Oct 28 '14 at 14:43
  • 1
    Ironically, the reason for the blank link is: *Unless the entire docstring fits on a line, place the closing quotes on a line by themselves. This way, Emacs' fill-paragraph command can be used on it.* – Felipe Jan 20 '17 at 16:02