[Python-ideas] Extend docstring construction

[Zac Burns]

Greetings,

I would like to see python's doc-string creation extended to allow for %
style string substitution.

Rationale:
This allows for patterns that keep doc-strings up-to-date without certain
types of boilerplate maintenance. For instance:

Including additional information from the module:

class Colors(Enum):
RED = (255, 0, 0)

def acceptsColor(color):
"""
color could be any:
%s
""" % '\n\t'.join('Color.' + color for color in publicDir(Colors))

Including docs of other functions
def _localFunction():
"Keeping the docstring with the function that does the work, so it's more
likely to keep up to date"

def publicFunction():
"%s" % _localFunction.__doc__


Drawbacks:
Executing code to retrieve a doc-string is considered a security
vulnerability. (Right now only the abstract syntax tree is used to get
docstrings)

In theory this could be backwards incompatible with existing code... but
that code would have to be relying on the side effect of some string
substitution line without doing anything with the new string - yuck.


Thoughts?

--
Zachary Burns
(407)590-4814
Aim - Zac256FL
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20101205/08b5bdb2/attachment.html>