python - how does one include a variable in the doc string?

Question

I'm using the cmd module. there's a command that I'd like to document like this:

def do_this(self,arg)
    "this command accepts these values {values}".format(values="legal values")

the reasoning being I'd like to type that list of legal values only once. I found I can change the docstring later, but I think that's a hack. Is there a way to do this?

Antti Haapala -- Слава Україні · Accepted Answer · 2016-03-18T18:31:08.557

9

Changing the docstring afterwards (by assigning to do_this.__doc__) is the only way.

Or if you want it to look nicer, you can use a decorator - but it still assigns to do_this.__doc__.

def doc(docstring):
    def document(func):
        func.__doc__ = docstring
        return func

    return document

@doc("this command accepts these values: {values}".format(values=[1, 2, 3])
def do_this(self, arg):
    pass

edited Mar 18 '16 at 18:31

answered Mar 18 '16 at 18:14

Antti Haapala -- Слава Україні

129,958
22
279
321

1

You should use `functools.wraps` for the decorator so you don't lose anything? – gerrit Mar 18 '16 at 18:16
@gerrit negative, this is not a wrapper (renamed the inner func to to `document`) – Antti Haapala -- Слава Україні Mar 18 '16 at 18:17
1

clever, I'll have to check out decorators. I'm new to python, and feel like I'm drinking from a firehouse at this point. – kdubs Mar 18 '16 at 18:28
one quick question on this. may I use that same @doc on multiple functions? or do I need a unique doc function for each do_this function? – kdubs Mar 18 '16 at 18:33
1

@kdubs this is reusable, naturally. You can have it in one module and import to others as you see fit. – Antti Haapala -- Слава Україні Mar 18 '16 at 18:37
yes, just tried it out. seems pretty good. the doc string is still near the function. – kdubs Mar 18 '16 at 18:42

Mikhail Gerasimov · Answer 2 · 2016-03-18T18:21:34.810

1

As you have this values in variable, you can reference to it in doc:

# mymodule.py
legal_values = {'one', 'two', 'three'}

def do_this(self,arg)
    """this command accepts these values: see `mymodule.legal_values`"""

edited Mar 18 '16 at 18:21

answered Mar 18 '16 at 18:18

Mikhail Gerasimov

36,989
16
116
159

1

tried this. didn't seem to work. those are backticks around legal_values? – kdubs Mar 18 '16 at 18:29
@kdubs they work if you make a HTML document of the module contents using Sphinx, similar to the Python docs. In there there'd be a hyperlink. It wouldn't work specially in the online `help` though. – Antti Haapala -- Слава Україні Mar 18 '16 at 18:32
1

@kdubs it doesn't insert values into docstring, but it's information for user, where to find this values. When I'll type `help(do_this)` or will see `do_this` in source, i'll understand i should see `help(mymodule.legal_values)` for this values. – Mikhail Gerasimov Mar 18 '16 at 18:39
1

ah. ok. I think the other answer is what I want then. it shows up in the help with cmd – kdubs Mar 18 '16 at 18:44

python - how does one include a variable in the doc string?

2 Answers2

Linked