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?

Answer 1

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

Answer 2

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`"""