dunder-docs (was Python is DOOMED! Again!)

[Rustom Mody]

On Monday, February 2, 2015 at 10:57:27 AM UTC+5:30, Vito De Tullio wrote:
> Steven D'Aprano wrote:
> 
> > Checking the REPL first would have revealed that [].__dir__ raises
> > AttributeError. In other words, lists don't have a __dir__ method.
> 
> ?
> 
> Python 3.4.2 (default, Nov 29 2014, 00:45:45) 
> [GCC 4.8.3] on linux
> Type "help", "copyright", "credits" or "license" for more information.
> >>> [].__dir__()
> ['sort', '__contains__', '__init__', '__ge__', 'count', '__class__', 
> '__format__', '__mul__', 'index', '__rmul__', '__hash__', '__iter__', 
> 'clear', '__subclasshook__', '__getitem__', 'reverse', 'append', '__ne__', 
> 'pop', '__reduce__', '__add__', 'extend', '__gt__', '__sizeof__', 
> '__setattr__', '__imul__', '__dir__', '__le__', 'insert', '__repr__', 
> '__str__', '__getattribute__', '__len__', '__lt__', 'remove', '__new__', 
> '__reduce_ex__', 'copy', '__reversed__', '__delattr__', '__eq__', 
> '__setitem__', '__iadd__', '__doc__', '__delitem__']
> >>> 

Sure
But as I said (and probably Steven checked):

$ python
Python 2.7.8 (default, Oct 20 2014, 15:05:19) 
[GCC 4.9.1] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> [].__dir__
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'list' object has no attribute '__dir__'

---------------
My point was more methodological/sociological than technical:

Are these dunder methods as 'internal' as say the register-allocation used
by a C compiler?

In which case the language implementer is entitled to tell the vanilla programmer: "Dunder methods (and their changingness) is none of your business"

If however they are more on the public façade of the language then some better
docs would be nice