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

[Nick Coghlan]

On Tue, Mar 15, 2011 at 9:42 AM, Tim Lesher <tlesher at gmail.com> wrote:
> 2. Add a new class attribute that uses the same mechanism, with a
> different name (e.g., __api__).
> Pro: fairly easy to explain; because it doesn't share a name with
> __all__ its semantics can be tweaked without confusing people.
> Con: slight additional cognitive burden of a new feature
>
> I'm implementing both of these separately this week to see which works
> better in practice.  So far I'm liking __api__ better, with these
> semantics:
>
> 1. Classes without __api__ are treated just as they are today.
> 2. __api__ on classes works just like __all__ on modules (only special
> names, plus its contents are documented)
> 3. Additionally, __api__ can take an Ellipsis.  That makes the __api__
> list additive--pydoc documents everything it normally would, *plus*
> the contents of __api__
> 4. __api__ is added to pydoc's "hidden names" list; since its only
> purpose is to help generate docs, its value would be of little use in
> the generated docs themselves.
>
> Point 3 (Ellipsis) is unusual, but to me it makes the declaration read
> well and solves the namedtuple case succinctly and compatibly, without
> changing a published API.  It also could be used to address the issue
> of stdlib classes that have non-underscored members that really
> shouldn't be considered part of the "public" API, but can't be renamed
> now for fear of breaking code.

The challenge here is how it would interact with inheritance. pydoc
couldn't use normal attribute lookup, it would have to walk the MRO
manually, only applying __api__ to the specific class that defined it.

Cheers,
Nick.

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