Documentaion of dunder methods

[Rustom Mody]

On Tuesday, May 26, 2015 at 7:47:41 AM UTC+5:30, Steven D'Aprano wrote:
> PEP 8 states that developers should never invent their own dunder methods:
> 
>     __double_leading_and_trailing_underscore__ : 
>         "magic" objects or attributes that live in user-controlled
>         namespaces. E.g. __init__ , __import__ or __file__ . Never 
>         invent such names; only use them as documented. 
> 
> https://www.python.org/dev/peps/pep-0008/#naming-conventions
> 
> 
> In other words, dunder methods are reserved for use by the core developers
> for the use of the Python interpreter.
> 
> Apart from PEP 8, is this documented anywhere in the official documentation?
> If so, I have been unable to find it.

Thanks for bringing this up.
dunder methods are a super-powerful and very pythonesque feature rendered 
somewhat useless by bad documentation.
Also I happen to disagree with (the literal rendering of your:

> In other words, dunder methods are reserved for use by the core developers
> for the use of the Python interpreter.

Of course defining YOUR OWN dunder method, disregarding the intended protocol
for that dunder method's usage, should not be done.
However if you interpret your statement as "Just dont go near them" it seems
like they are some kind of best-avoided leaky-abstraction of the (C)python 
implementation. And I guess you dont really want to assert that!!

What I'd like to see in the docs is something that 'zips' the operator table 
with the corresponding dunder method.  Something like:
| + | __add__ __radd__ |
| []| __getitem__ |
etc

Yeah I realize the most critical dunders dont 'have' an associated operator --
__init__.  But even there I'd put something like
|Class constructor¹| __init__

¹ Yeah I know about the 'initializer-vs-constructor' debates. Not really taking
a side on that one