PEP 257 docstring trim in standard library?
Question:
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.
Answers:
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.
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.
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.