More detailed explanation of how in place operators work, and how they are related to the operator module iadd, isub, ... functions.

Submitted following this message on python-list:

http://mail.python.org/pipermail/python-list/2010-August/1254243.html

I agree that the docs for augmented assignments and the corresponding method and funciton can and should be improved.

But I do not like this as is. In particular, Python does not have in-place operators; it has methods that optionally do an operation in-place if the first argument (self) is mutable. I think adding "" is insufficient to avoid the confusion of the incorrect term. What I think should be said is that the ixxx methods and the corresponding operator.ixxx functions implement the operation part of operation-augmented assignments.

For the operator doc, I think we should expand the initial paragraph ("The operator module ...") a bit so that less needs to said specifically for the ixxx functions.

Also, most of your explanation is really about augmented assignment and the .__ixxx__ special methods, not specifically about operator.ixxx functions, and might better be added to the subsection 3.3.6. Emulating numeric typesof the special methods section (and cross-referenced from the operator doc) or even used to improve 6.2.1. Augmented assignment statements, and not buried in the operator doc. If people are confused about the .ixxx functions, they are probably confused also about a.a. and .__ixxx__ methods.

So I would like to attack the whole problem and expand this issue to "Improve operator-augmented assginment docs." and cover all three relevant doc areas, starting with
6.2.1. Augmented assignment statements. As already hinted, I would like to expand the title to "Operator-augmented assignment statements.".

I would like there to be a prototype example near the top: either "target_arg op= arg", with op explained as one of +-*/... or "target_arg += arg" as a specific example, or both. Since the target is also an arg reference, it obviously must refer to a single existing object. Then discuss the two cases of target immutable and mutable, as the current doc and your proposal does.

Otherwise in this section, I am mystified by the reference of "(See section Primaries for the syntax definitions for the last three symbols.)". I have also forgotten the meaning of "With the exception of assigning to tuples "; i should just be stated.

As already stated, I also believe the explanation of .__ixxx__ methods in 3.3.6. Emulating numeric types could be improved a bit.

Consider breaking the operator module documents into sections, grouping all of the in-place ops into the last section.  Start that section with a full description of how in-place works in python and show some examples of successful way to use the in-place operators.

Right now, the docs are somewhat misleading because they imply that the i-functions can be used in the same was as their counterparts.

Terry: I agree that augmented assignement should be described better in the language reference.  I guess that would warrant opening another issue?

However I tend to think that the term "in-place operation" is a good one.

BTW:

- the reference of "(See section Primaries for the syntax definitions for the last three symbols.)" is probably there to point to the definition of what can go on the left side of the augmented assignement symbol (what used to be called an "lvalue")

- "With the exception of assigning to tuples ": this refers to the fact that whereas x, y, z = l is correct syntax, x, y, z += l isn't.

Raymond: I agree that the operator doc would be clearer if better structured.

So I put forward another patch to operator.rst, structuring it more clearly and providing a more detailed introduction to the "In-place operations" section, but not trying to detail the workings of augmented assignement in general.

Since Raymond has grabbed this, I will let him decide on its scope.
I agree with sectioning the operator doc and intended to suggest that.

The term 'in-place operation' is fine when accurate. The term 'in-place operator', which is what you wrote and what I criticized, is not as it is never accurate and has confused and mislead people. For one thing, it leads them to forget that augmented assignment statements are statements that *always* do an assignment. For another, they forget that the operation can only be in-place for mutables. That is my observation based on years of reading c.l.p./python-list. An 'in-place operator' would do an operation in-place without any assighment and would only work for mutables. Python has neither operators nor functions nor syntax with those characteristics.

See r87862.