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? — mkrieger1
– mkrieger1, Commented Jan 26, 2022 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
– Wouter van Ooijen, Commented Jan 26, 2022 at 12:46

Kelly Bundy · Accepted Answer · 2022-01-27 20:52:09Z

31

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, 2022 at 20:52

Kelly Bundy

28k7 gold badges34 silver badges76 bronze badges

answered Jan 26, 2022 at 15:08

Colonel Thirty Two

26.9k9 gold badges52 silver badges94 bronze badges

Sign up to request clarification or add additional context in comments.

3 Comments

Wouter van Ooijen Over a year ago

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 Over a year ago

I guess I'll have to preprocess the whole file before passing it to sphinx.

J Agustin Barrachina Over a year ago

How would you make it work on sphinx? Indeed it is not working with Sphinx.

chaos.ct · Accepted Answer · 2023-07-26 10:37:19Z

9

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, 2023 at 10:37

chaos.ct

1,1011 gold badge8 silver badges20 bronze badges

1 Comment

NameVergessen Over a year ago

Do you know if this works for napoleon sphinx?

tvt173 · Accepted Answer · 2024-04-11 23:27:00Z

1

a bit annoying, but another option is to generate the python file with a templating engine like jinja2. you will need to additionally create the template for your file and the logic to render it, but you will end up with a "normal" python file in the end, with literal docstrings that are compatible with sphinx, etc. etc.

answered Apr 11, 2024 at 23:27

tvt173

1,90621 silver badges18 bronze badges

Collectives™ on Stack Overflow

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

3 Answers 3

3 Comments

1 Comment

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

3 Comments

1 Comment

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related