[Python-Dev] Customization docs

[David Abrahams]

A few questions about customization and the docs, TIA:

------

http://www.python.org/dev/doc/devel/ref/customization.html tosses off this
sentence in the section on rich comparisons:

"A rich comparison method may return NotImplemented if it does not
implement the operation for a given pair of arguments."

...but it says nothing about the effect that will have. Using Thomas
Heller's search engine, I found
http://www.python.org/dev/doc/devel/ref/types.html#l2h-59, which says

"...Numeric methods and rich comparison methods may return this value if
they do not implement the operation for the operands provided. (The
interpreter will then try the reflected operation, or some other fallback,
depending on the operator.) "

This seems like the wrong place to bury the description of the mechanism
for operating on heterogeneous arguments. Shouldn't a short description go
into the Customization section of the docs?

-------

It also mentions, "There are no reflected (swapped-argument) versions of
these methods (to be used when the left argument does not support the
operation but the right argument does)..."

since these are the first binary operators described the whole concept of
reflected methods hasn't been introduced yet, and the user has no reason to
think that reflected versions should exist.

[incidentally, "reflected" and "reflection" produce no hits with Thomas'
engine]


-------
>From what I could find in the docs, it's completely non-obvious how the
following works for immutable objects in containers:

>>> x = [ 1, 2, 3]
>>> x[1] += 3
>>> x
[1, 5, 3]

Is the sequence of operations described someplace?
How does Python decide that sequence elements are immutable?


+---------------------------------------------------------------+
                  David Abrahams
      C++ Booster (http://www.boost.org)               O__  ==
      Pythonista (http://www.python.org)              c/ /'_ ==
  resume: http://users.rcn.com/abrahams/resume.html  (*) \(*) ==
          email: david.abrahams@rcn.com
+---------------------------------------------------------------+