docstring that use globals?

kj no.email at please.post
Sat Oct 16 11:51:32 EDT 2010



Consider the following Python snippet: 

SEPARATOR = '+'

def spam(ham, eggs):
    """Return a hash of ham and eggs.

    The variables ham and eggs are tuples of strings.  The returned
    "hash" is a dict made from the pairs returned by zip(ham, eggs).
    If ham contains repeated keys, the corresponding values in eggs
    are concatenated using the string "SEPARATOR".

    For example, spam(('a', 'b', 'a'), ('x', 'y', 'z')) returns
    {'a': 'xSEPARATORz', 'b': 'y'}."""

    # implementation follows...


Of course, as written, the docstring above is no good.  All
occurrences of the string "SEPARATOR" in it should be replaced with
the actual value of the global variable SEPARATOR, which in this
case is the string '+'.

My first attempt at achieving this effect was the following:

SEPARATOR = '+'

def spam(ham, eggs):
    """Return a hash of ham and eggs.

    The variables ham and eggs are tuples of strings.  The returned
    "hash" is a dict made from the pairs returned by zip(ham, eggs).
    If ham contains repeated keys, the corresponding values in eggs
    are concatenated using the string "%(SEPARATOR)s".

    For example, spam(('a', 'b', 'a'), ('x', 'y', 'z')) returns
    {'a': 'x%(SEPARATOR)sz', 'b': 'y'}.""" % globals() 

    # implementation follows...


...which, of course (in retrospect), does not work, since only a
string literal, and not any ol' string-valued expression, at the
beginning of a function's body can serve as a docstring.

What's the best way to achieve what I'm trying to do?

(Of course, all these acrobatics are hardly worth the effort for
the simple example I give above.  In the actual situation I'm
dealing with, however, there are a lot more docstrings and global
variables in the mix, and at this early stage of the development,
the values of the globals are still fluid.  I'm trying to minimize
the effort required to keep the docstrings current, while still
retaining the freedom to adjust the values of the globals.  Also,
FWIW, most of these globals are merely default values that can be
overridden at runtime.)

TIA!

~kj



More information about the Python-list mailing list