Python Documentation Improvement

[Steven D'Aprano]

Archana Pandey wrote:

[...]
> A = a + 1 and a += 1  both behave in same way for all data types except
> python Lists

I cannot think of any other mutable data type that supports + but there are
mutable data types that support other augmented assignment operators:


py> a = set("abcd")
py> b = a  # now b and a both point to the same set
py> a -= set("cat")
py> print b
set(['b', 'd'])


To understand this behaviour, you have to understand three facts:


(1) Assignment is name-binding, not copying. So when you say "b = a", that
makes "b" another name for the same object as "a", not a copy of "a".

(2) Augmented assignments like += -= &= etc. are not just permitted but
*encouraged* to use in-place modification with mutable types such as list
and set.

(3) The standard operators + - & etc. are expected to create new objects,
not modify the existing object.

That should explain the difference in behaviour between regular assignment
and augmented assignment.


[...]
> NOTE: Documentation should provide sufficient information for such
> scenario.

Personally, I think that the documentation is clear enough, but I welcome
suggestions for improvement. Can you point us to the parts of the
documentation which you think are not clear enough? Do you have some
suggested improvements?



-- 
Steven