[New-bugs-announce] [issue16801] Preserve original representation for integers / floats in docstrings

[Larry Hastings]

New submission from Larry Hastings:

The line declaring the function dbm.open looks like this:
    def open(file, flag='r', mode=0o666):

The docstring for dbm.open looks like this:
    open(file, flag='r', mode=438)

Obviously 438==0o666.  But the author used the octal representation because it's more readable.  Unfortunately Python throws that enhanced readability away when it round-trips the rvalue from a string into an integer and back into a string again for the docstring.

It might be an improvement if Python preserved the original source code's representation for integer (and perhaps float) default arguments for parameters.  I haven't looked at the code that does the parsing / builds the docstring, but I suspect we could hang the original representation on the AST node and retrieve it when building the docstring.

The only problem I can forsee: what about code that uses local variables, or computation including perhaps function calls, to calculate default values?  On the one hand, the local variable or the function call may be inscrutable--on the other, perhaps the magic integer value it replaced was no better.  Or we could have a heuristic, like if the original representation contains internal spaces or parentheses we use str(rvalue), otherwise we use the original representation.

----------
components: Interpreter Core
messages: 178383
nosy: larry
priority: normal
severity: normal
status: open
title: Preserve original representation for integers / floats in docstrings
type: enhancement
versions: Python 3.4

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue16801>
_______________________________________