[docs] [Tutor] special attributes naming confusion

[Jerry Hill]

On Wed, Jun 6, 2012 at 4:32 PM, Dave <davestechshop at gmail.com> wrote:
> I'm not sure where this comment belongs, but I want to share my perspective
> on the documentation of these special method names. In the following section
> there is an inconsistency which could be confusing to someone just learning
> Python (e.g., me).
>
> In the sentence on implementing custom mapping objects, the recommended
> method names are listed as the short calling names: eys(), values(),
> items(), etc.
>
> But, in contrast, in the sentence on implementing sequence types, the
> recommended method names are listed as the double underscore internal
> implementation names: __add__(), __radd__(), __iadd__(), __mul__(), etc.
>
> Here's the section of the documentation with this inconsistency. I think it
> would help to use one or the other of these pairs (calling name vs. internal
> implementation name) consistently in this section.

Those aren't pairs, where you can implement either one.  You have to
implement ALL of those methods to correctly emulate one of the built
in container classes.  The difference is that the "normal" method
names (the ones without double underscores) are meant to be called
directly on an instance of your class.  The double underscored names
are called by the internals of python, often in a variety of different
places.

For instance, the __iter__() method is called by the iter() built-in.
It can also called by any other piece of code that needs to acquire an
iterator from a generic container object.  There is no list of all
such pieces of code that could ever call the __iter__() method of your
object.

Jerry