How to put a variable into Python docstring

Question

So I'm trying to create a "dynamic" docstring which is something like this:

ANIMAL_TYPES = ["mammals", "reptiles", "other"]  def func(animalType): """ This is a sample function.      @param animalType: "It takes one of these animal types %s" % ANIMAL_TYPES """ 

to basically let the docstring for @param animalType show whatever ANIMAL_TYPES has; so that when this variable is updated, the docstring will be updated automatically.

Unfortunately, it doesn't seem to work. Does anyone know if there is a way of achieving this?

Answer 1

One way to do this would be to use a decorator. I'm not sure how I feel about this; I actually searched for commentary on this method and found this answer, which rightly notes that it could mask a design problem. But your use case seems sound to me at first glance.

In any case, here's a fairly elegant way to achieve the result you're looking for:

>>> def docstring_parameter(*sub): ...     def dec(obj): ...         obj.__doc__ = obj.__doc__.format(*sub) ...         return obj ...     return dec ...  >>> @docstring_parameter('Ocean') ... def foo(): ...     '''My Docstring Lies Over The {0}''' ...     pass ...  >>> @docstring_parameter('Sea') ... def bar(): ...     '''My Docstring Lies Over The {0}''' ...     pass ...  >>> @docstring_parameter('Docstring', 'Me') ... def baz(): ...     '''Oh Bring Back My {0} To {1}''' ...     pass ...  >>> foo.__doc__ 'My Docstring Lies Over The Ocean' >>> bar.__doc__ 'My Docstring Lies Over The Sea' >>> foo.__doc__ 'My Docstring Lies Over The Ocean' >>> baz.__doc__ 'Oh Bring Back My Docstring To Me'