Can a Python docstring be calculated (f-string or %-expression)?

Question

Is it possible to have a Python docstring calculated? I have a lot of repetitive things in my docstrings, so I'd like to either use f-strings or a %-style format expression.

When I use an f-string at the place of a docstring

importing the module invokes the processing
but when I check the __doc__ of such a function it is empty
sphinx barfs when the docstring is an f-string

I do know how to process the docstrings after the import, but that doesn't work for object 'doc' strings which is recognized by sphinx but is not a real __doc__'s of the object.

Does this answer your question? [How do I programmatically set the docstring?](https://stackoverflow.com/questions/4056983/how-do-i-programmatically-set-the-docstring) — mkrieger1, Jan 26 '22 at 12:39
No, that is basically what I do now because an f-string as docstring doesn't seem to work, at least not with sphinx, and it is not recognized by checker tools. But it does seem to be 'executed' by normal Python. — Wouter van Ooijen, Jan 26 '22 at 12:46

score 13 · Accepted Answer · edited Jan 27 '22 at 20:52

13

Docstrings in Python must be regular string literals.

This is pretty easy to test - the following program does not show the docstring:

BAR = "Hello world!"

def foo():
        f"""This is {BAR}"""
        pass

assert foo.__doc__ is None
help(foo)

The Python syntax docs say that the docstring must be a "string literal", and the tail end of the f-string reference says they "cannot be used as docstrings".

So unfortunately you must use the __doc__ attribute.

However, you should be able to use a decorator to read the __doc__ attribute and replace it with whatever you want.

edited Jan 27 '22 at 20:52

Kelly Bundy

23,480
7
29
65

answered Jan 26 '22 at 15:08

Colonel Thirty Two

23,953
8
45
85

1

Thanks, that is what I feared. Unfortunately, post-processing the \_\_doc__ strings doesn't work for objects, which are important for me ;( – Wouter van Ooijen Jan 26 '22 at 15:14
I guess I'll have to preprocess the whole file before passing it to sphinx. – Wouter van Ooijen Jan 26 '22 at 15:15
How would you make it work on sphinx? Indeed it is not working with Sphinx. – J Agustin Barrachina May 05 '23 at 12:55

score 2 · Answer 2 · answered Jul 26 '23 at 10:37

2

We had the same problem, and what we might end up doing is this:

BAR = "Hello world!"

class A():
    __doc__ = f"""This is {BAR}"""
    pass

help(A)

answered Jul 26 '23 at 10:37

chaos.ct

1,001
1
7
18

Can a Python docstring be calculated (f-string or %-expression)?

2 Answers2

Linked