Extend docstring construction
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
On 12/4/2010 9:31 PM, Zac Burns wrote:
I am sympathetic to the purpose, having recently run into such a problem. But...
1, The need to reliably recognize that an expression is meant to define a docstring rather than that be part of the runtime code. A string expression is senseless as runtime code. However, other expression statements are executed for their side-effects, and most any expression have have such. 2. You are proposing to use the semi-deprecated %-as-format operator.
Executing code to retrieve a doc-string is considered a security vulnerability.
The string would have to be computed along with the object it gets attached to. -- Terry Jan Reedy
On Sun, Dec 5, 2010 at 12:31 PM, Zac Burns <zac256@gmail.com> wrote:
Just roll your own decorator if you want to do something like this: def format_docstring(*args, **kwds): def docstringFormatter(f): fmt = f.__doc__ f.__doc__ = fmt.format(*args, **kwds) return f return docstringFormatter @format_docstring("Any text you like") def sample(): """Include a supplied string in the docstring: {} """ help(sample) ============================= Help on function sample in module __main__: sample() Include a supplied string in the docstring: Any text you like ============================= Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 12/4/2010 9:31 PM, Zac Burns wrote:
I am sympathetic to the purpose, having recently run into such a problem. But...
1, The need to reliably recognize that an expression is meant to define a docstring rather than that be part of the runtime code. A string expression is senseless as runtime code. However, other expression statements are executed for their side-effects, and most any expression have have such. 2. You are proposing to use the semi-deprecated %-as-format operator.
Executing code to retrieve a doc-string is considered a security vulnerability.
The string would have to be computed along with the object it gets attached to. -- Terry Jan Reedy
On Sun, Dec 5, 2010 at 12:31 PM, Zac Burns <zac256@gmail.com> wrote:
Just roll your own decorator if you want to do something like this: def format_docstring(*args, **kwds): def docstringFormatter(f): fmt = f.__doc__ f.__doc__ = fmt.format(*args, **kwds) return f return docstringFormatter @format_docstring("Any text you like") def sample(): """Include a supplied string in the docstring: {} """ help(sample) ============================= Help on function sample in module __main__: sample() Include a supplied string in the docstring: Any text you like ============================= Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
participants (3)
-
Nick Coghlan -
Terry Reedy -
Zac Burns