[Python-Dev] inconsistent abstractmethods behavior; lack of documentation (original) (raw)

Nick Coghlan ncoghlan at gmail.com
Sun Aug 7 15:03:04 CEST 2011

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

More information about the Python-Dev mailing list