Terry J. Reedy tjreedy@udel.edu added the comment:

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.

---------- nosy: +terry.reedy stage: -> patch review versions: +Python 2.7, Python 3.1, Python 3.2 -Python 3.3

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9717 _______________________________________

Changes by Raymond Hettinger rhettinger@users.sourceforge.net:

---------- assignee: docs@python -> rhettinger

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9717 _______________________________________

Terry J. Reedy tjreedy@udel.edu added the comment:

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.

----------

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9717 _______________________________________