Python – Sharing Docstrings Between Similar Functions

documentationprogramming practicespython

Assuming we have different classes with methods that possess the exact same description, however execute code a bit differently for the same return type.

class Foo:
    """This is the Foo class Docstring. It is a type of Bar source."""
    def getBar(self,pos):
        """
        This is the Bar method. 
        It calculates and returns the Bar field effect generated 
        by this source based on `pos`
        """   
        effect = pos + 1 
        return effect

class Waldo:
    """This is the Waldo class Docstring. It's also a type of Bar source."""
    def getBar(self,pos):
        """
        This is the Bar method. 
        It calculates and returns the Bar field effect generated 
        by this source based on `pos`
        """   
        effect = pos + 2 
        return effect

This is a problem because, assuming there are many Bar sources, if one changes the description for getBar() they'll have to repeat the change for all the sources.

How could one make it so there's a single Docstring shared between both or more of these, having it so a change in Foo.getBar() would change the description of Waldo.getBar() for tooltips?

A way of restructuring or overriding in order to achieve the same effect would also be welcome.

I've tried the __doc__+=Foo.getBar().__doc__ approach in this question but it seems unreliable (using an environment like Spyder for instance, it recognizes it as a local variable).

Best Answer

Different tools access docstrings differently. For example, having a common base class that provides this docstring may be sufficient for some tools but not others.

The most general approach would be to define a functools.wraps() like decorator that copies the docstring of a function, e.g.:

def is_documented_by(original):
  def wrapper(target):
    target.__doc__ = original.__doc__
    return target
  return wrapper

class Waldo:
  @is_documented_by(Foo.getBar)
  def getBar():
    ...

But since this requires executing the Python code, static analyzers like Pylint may not like this. The best solution depends on the tools you are going to use.

Related Solutions

Python Documentation – How to Split Between Docstrings and Sphinx

The Python standard library keeps all of its Sphinx documentation separate, forgoing the autodoc feature entirely, and uses much more brief docstrings in the source files. Thus, the following practice is perhaps best:

Docstrings in source code should not use Sphinx directives, using only light reST formatting for readability. Because (good) Python code is quite clear on its own, keep docstrings informative but simple. These should be primarily for project devs and anyone digging into the source code.
Actual end-user (or developers for libraries) documentation should be taken care of by Sphinx. Use autodoc when suitable, adhering to the above.

Sharing Context Variables Between Python Functions – Patterns

You might look into the Reader or State monads; they can be used for sharing data between (pure, monadic) functions, without resorting to explicit parameters or the like.

There's a tutorial series on F# for fun and profit about the State monad (AKA Workflow in F# parlence). I also gave a description of it in this SO answer that appears to be fairly approachable.

There are some implementations of other monads in python that you could reference too, if you have to implement your own.

Many people (myself included) find monads challenging at first, so if you're not familiar with the concept then I'd recommend looking at some of the simpler monads like Maybe or Either, and then perhaps Reader or Writer, before tackling State. The Python implementations linked to above may make things more clear for you than what you're likely to find elsewhere online (which would probably be Haskell).

A few caveats: there is still a little overhead over just functions, since the monad is involved, and this has to be used with functions; I don't think you could do this with class methods (though I could be wrong -- I've never tried it!).

UPDATE:

The "monads in python" page/lib I linked to above actually does have a state-monad implementation; check out the code starting at ###### StateChanger Monad ######### for the definition and examples.

EDIT in response to question in comment:

Yes, that's the way you'd do it -- to be extra clear, the arguments you declare the function with should not include the environment variables, just the ones the function would need normally; the environment variables will be accessible through the monadic get and set functions.

A Python example using the notation given in the "monads in python" link above:

@do(StateChanger) # <-- this makes makes it a stateful computation
def my_stateful_function1(arg):
    # do something with `arg` here
    # then put it in the state:
    yield dict_state_set(key, var_from_arg)
    # I believe you can leave out `mreturn` for this

@do(StateChanger)
def my_stateful_function2(arg1, arg2):
    # something with `arg1` here
    # get the state chained via the monad:
    state = yield get_state()
    # do something else stateful:
    yield my_stateful_function1(arg2)
    # do something with `state` dict here
    # return; you have to use `mreturn` instead of `return`:
    mreturn(some_value)

To run this you'd call:

ret_val = my_stateful_function2("hello","world").run(initial_state_dict)

and your return value would be a tuple:

(return_value_of_function, final_state_dict) = ret_val

Remember to use yield when calling other stateful functions.

Admonition: Be careful about modifying the state in your functions since the Python dictionary type is mutable. You can get and set state vars, as well as apply a (lambda) function to them; you may wish to stick with this rather than pulling the state out and mutating it willy-nilly.

Best Answer

Related Solutions

Python Documentation – How to Split Between Docstrings and Sphinx

Sharing Context Variables Between Python Functions – Patterns

Related Topic