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

[Nick Coghlan]

On Sun, Aug 7, 2011 at 10:45 PM, Guido van Rossum <guido at python.org> wrote:
> On Sat, Aug 6, 2011 at 5:58 PM, Terry Reedy <tjreedy at udel.edu> wrote:
>> 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.
>
> I disagree. If you see a __dunder__ name which has no documentation
> you should simply refrain from using it, and no harm will come to you.
> There is a clearly stated rule in the language reference saying this.
> It also documents some specific __dunder__ names that are significant
> for users and can be used in certain specific ways (__init__,
> __name__, etc.). But I see no reason for a requirement to have an
> exhaustive list of undocumented __dunder__ names, regardless if they
> are supposed to be special for CPython only, for all Python versions,
> for the stdlib only, or whatever.

Indeed, the way it tends to work out in practice (especially for pure
Python code) is that the other implementations will just copy the
internal details from CPython, and only if that turns out to be
problematic for some reason will they suggest a clarification in the
language reference to separate out the details of Python-the-language
from CPython-the-implementation in a particular case. That doesn't
happen very often, but when it does it generally seems to be because
they want to do something more sane than what we do, but the more sane
behaviour is hard for us to implement for some reason. Even more
rarely such questions may expose an outright bug in the reference
implementation (e.g. the operand precedence bug for sequence objects
implemented in C that's on my to-do list for 3.3).

Cheers,
Nick.

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