On Sun, Aug 7, 2011 at 10:45 PM, Guido van Rossum <gu...@python.org> wrote: > On Sat, Aug 6, 2011 at 5:58 PM, Terry Reedy <tjre...@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 | ncogh...@gmail.com | Brisbane, Australia _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
