[Python-Dev] pydoc for named tuples is missing methods

[Nick Coghlan]

On Mon, Mar 14, 2011 at 2:33 AM, Greg Ewing <greg.ewing at canterbury.ac.nz> wrote:
> Tim Lesher wrote:
>
>> Because named tuple prefixes a single underscore to its added method
>> names (_asdict, _replace, and _make), those methods' docstrings are
>> omitted from pydoc:
>
> IMO these should be called __asdict__, __replace__ and
> __make__. Users are perfectly entitled to make up their
> own single-underscore names, so using a single underscore
> is not sufficient to prevent name collisions.

True, but all those underscores are a PITA to type and read for
methods that are meant to be called directly. A single leading
underscore is enough to move them out of the way of the standard
public fields of a named tuple. Giving a nominally private name to a
field that is already publically accessible via index would be
nonsensical.

There are two relatively simple ways forward I can see:

A. Add a __public__ attribute that pydoc (and import *) understand.
This would overrride the default "this is private" detection and add
affected names to the public list (without needing to respecify all
the "default public" names - this is important in order to support
subclassing correctly)

B. Add a different prefix to the named tuple methods (e.g ntup_asdict,
ntup_replace, ntup_make).

There's also an even more radical alternative:

C. Add syntax for bypassing the instance lookup when accessing attributes.

If "obj..replace(*args)" (or whatever - this specific example arguably
fails the "syntax shall not look like grit on Tim's monitor" test) was
guaranteed to do the moral equivalent of "type(obj).replace(obj,
*args)", then these could all become normal public methods, with the
caveat that access via the class should be forced when using them.
This would also make a *lot* of the Python code dealing with magic
methods a fair bit cleaner (we currently have to do the type(obj)
dance manually in various places to avoid metaclass confusion issues).

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia