Menu
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.
502
Declaring Docstrings: The docstrings are declared using ”'triple single quotes”' or “””triple double quotes””” just below the class, method or function declaration. All functions should have a docstring.
Docstrings are accessible from the doc attribute (__doc__) for any of the Python objects and also with the built-in help() function. An object's docstring is defined by including a string constant as the first statement in the object's definition.
Use comments to explain how code works. Comments are great for leaving notes for people working on your program. Docstrings provide documentation about functions, classes, and modules. Use docstrings to teach other developers how to use your program.
As mentioned above, Python docstrings are strings used right after the definition of a function, method, class, or module (like in Example 1). They are used to document our code. We can access these docstrings using the __doc__ attribute.
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.
193
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
