[Python-Dev] inconsistent __abstractmethods__ behavior; lack of documentation

[Terry Reedy]

On 8/6/2011 8:29 AM, Guido van Rossum wrote:

> Do you realize that __xxx__ names can have any semantics they darn
> well please?

That does not seem to be to be the issue Cristoff raised.

> If a particular __xxx__ name (or some aspect of it) is
> undocumented that's not a bug (not even a doc bug), it just means
> "hands off".

"__abstractmethods__" is used in the stdlib at least in abc.py:

95 class ABCMeta(type):
...
116 def __new__(mcls, name, bases, namespace):
...
123 for name in getattr(base, "__abstractmethods__", set()):
124 value = getattr(cls, name, None)
125 if getattr(value, "__isabstractmethod__", False):
126 abstracts.add(name)
127 cls.__abstractmethods__ = frozenset(abstracts)

Since this module implements a PEP (3119) and is not marked as CPython 
specific, it should run correctly on all implementations. So 
implementors need to know what the above means. (

The doc to abc.py invites readers to read this code:
**Source code:** :source:`Lib/abc.py`

For both reasons, this attribute appears to be part of Python rather 
than being private to CPython. If so, the special name *should* be 
documented somewhere.

If it should *never* be used anywhere else (which I suspect after seeing 
that it is not used in numbers.py), that could be said.

"__abstractmethods__: A special attribute used within ABCmeta.__new__ 
that should never be used anywhere else as is has a special-case effect 
for this one use."

The problem with intentionally completely not documenting names publicly 
accessible in the stdlib code or from the interactive interpreter is 
that the non-documentation is not documented, and so the issue of 
documentation will repeatedly arise. The special names section of 'data 
model' could have a subsection for such. "The following special names 
are not documented as to their meaning as users should ignore them." or 
some such.

-- 
Terry Jan Reedy