Using string formatting within class method docstrings

Question

I have a class with several similar methods, each with long docstrings that are similar but vary with regards to several phrases/words. I'd like to build a docstring template and then apply string formatting to it. Below is a clumsy implementation where the __doc__s are defined after the class methods.

capture_doc = """
%(direc)s normal.

a %(sym)s b."""

class Cls():    
    def a(self):
        pass
    def b(self):
        pass
    a.__doc__ = capture_doc % {'direc' : 'below', 'sym' : '<'}     
    b.__doc__ = capture_doc % {'direc' : 'above', 'sym' : '>'}

c = Cls()    
print(c.a.__doc__)

below normal.

a < b.

Question: is there a Python docs- or PEP-prescribed way to do this? I'd like to keep things basic, I've seen use of an @Appender decorator but think that's a bit fancy for my needs.

Moses Koledoye · Accepted Answer · 2017-07-20T21:27:21.180

8

You shouldn't do this. You seem to assume your docstring should only serve those who use your code and need help with how it works.

Docstrings are supposed to provide some form of the documentation for the associated object for those reading your code, so this makes your docstring half its worth. I doubt any one would love to go through the trouble of having to format those strings (in their heads or using the interpreter) to figure out what your code does or how it works.

From PEP 257:

What is a Docstring?

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.

[Emphasis mine]

With your implementation, one could pedantically argue you don't have docstrings albeit __doc__ attributes.

edited Jul 20 '17 at 21:27

answered Jul 20 '17 at 21:12

Moses Koledoye

77,341
8
133
139

Thank you, well put. So regarding the linked `pandas` code in my question, would you say that implementation is frowned upon also? Also, as alluded to in my question, is this your opinion or something the python gods have officially decreed? – Brad Solomon Jul 20 '17 at 21:15
@BradSolomon That is up to the pandas core developers. More so, docs for those seem to be way much longer as to make it justifiable to not want to repeat with minor modifications. Here, you have a few characters and I don't think repeating the doc flouts DRY. – Moses Koledoye Jul 20 '17 at 21:19
The strongest argument is in my opinion the fact that spelling out each documentation in the question does not violate the Don't Repeat Yourself principle: this documentation is simple and short, so there is little risk that something bad will happen when the code is updated. – Eric O. Lebigot Jan 21 '20 at 13:29
I would also say most docstrings are arguably read by users, not people who read the source code. Libraries are meant to be mostly used, not analyzed/deconstructed/maintained by external users. – Eric O. Lebigot Jan 21 '20 at 13:30
Finally, I would add a technical note: a docstring is indeed the literal described in PEP 257, but the question is obviously about method _documentation_, and `__doc__` is the documentation of a method (as repeatedly written at https://docs.python.org/3/reference/datamodel.html?highlight=__doc__)., which is indeed the subject of the question. – Eric O. Lebigot Jan 21 '20 at 13:30
"You shouldn't do this" is not an answer to the question. There are legitimate use cases for this, for example `click` uses docstrings for help text. – alexia May 24 '22 at 18:33

Using string formatting within class method docstrings

1 Answers1