34

PEP 257 says:

Docstring processing tools will strip a uniform amount of indentation from the second and further lines of the docstring, equal to the minimum indentation of all non-blank lines after the first line. Any indentation in the first line of the docstring (i.e., up to the first newline) is insignificant and removed. Relative indentation of later lines in the docstring is retained. Blank lines should be removed from the beginning and end of the docstring.

A function trim implementing this algorithm is then shown in the PEP.

I can find questions where people ask how to format docstrings and are referred to PEP 257 (e.g., this). I also see some info about tools that try to ensure your docstrings follow PEP 257 (e.g., this). What I can't find is any Python library that actually is a "docstring processing tool" that handles docstrings in the way defined in PEP 257 --- or at least, I can't find a tool that makes this docstring processing functionality directly available.

Does the function trim shown in PEP 257 exist in the standard library? Obviously I can paste the function into a file myself, but I'd prefer to use it from the standard library if I'm using some other computer where I want this functionality, instead of always copying and pasting from the PEP. Given that the function is in a PEP coauthored by the BDFL, I would have thought there would be some official or semi-official library that does this.

The reason I want this is to write a decorator that does some Python-internal reformatting of the docstrings of classes/functions. I don't want to generate HTML or anything else; I just want to change the actual docstrings of the actual objects. I want to take the plain-text __doc__ attribute of a Python object and reformat it into something that will serve as the plain-text __doc__ attribute of a Python object.

Antti Haapala -- Слава Україні
  • 129,958
  • 22
  • 279
  • 321
BrenBarn
  • 242,874
  • 37
  • 412
  • 384
  • Well, at a guess, `sphinx`, `pydoc`, et al are all going to do this. – Gareth Latty May 14 '13 at 02:39
  • @Lattyware: I clarified my question a bit. They may do it, but as far as I can see from the docs, they do it as part of much more heavyweight processing and don't provide any interface to simple manipulation of the docstring. They're aimed at generating HTML, etc., and don't seem to offer a direct way to just munge the plaintext docstring. – BrenBarn May 14 '13 at 02:47
  • I'm still having trouble understanding what you mean here, but a good portion of what sphinx does is pass your text through a restructuredtext parser (with some special extensions provided by sphinx), so you could really do whatever you want with it that way. – Jeff Tratner May 14 '13 at 03:35
  • @JeffTratner: I added a bit about this. It may be that Sphinx provides this, but the documentation doesn't make it at all clear how to access this functionality. The documentation is focused on outputting documentation to an external document. I want to reformat the actual `__doc__` attributes of Python objects. – BrenBarn May 14 '13 at 05:00

1 Answers1

51

In looking for an answer to a related question, I managed to find the answer to this one. The trim algorithm is implemented in inspect.cleandoc, of all places.

Cody Piersall
  • 8,312
  • 2
  • 43
  • 57
BrenBarn
  • 242,874
  • 37
  • 412
  • 384
  • 6
    TFW you look something up, find an answer, and see that you've already upvoted it. – Cyphase Dec 21 '19 at 21:51
  • @Cyphase - It's a good feeling (sort of), because it means that you didn't have to walk around remembering some detail ("no open loops!") and yet your "system" still brought you back around to the same answer again. – mlibby Jun 18 '20 at 16:40
  • 1
    @jaimet: Someone else already suggested `textwrap.dedent`, although their answer was deleted so you probably can't see it. Anyway, it's not what's asked for here, because it doesn't treat the first line specially as described in the quote given in the question. – BrenBarn Apr 14 '21 at 18:22