classification
Title: operator module - "in place" operators documentation
Type: Stage: patch review
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: arno, docs@python, rhettinger, terry.reedy
Priority: normal Keywords: patch

Created on 2010-08-30 18:49 by arno, last changed 2011-01-08 10:27 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
operator_inplace.diff arno, 2010-08-30 18:49 Patch to operator.rst review
operator_structured.diff arno, 2010-09-04 18:14 patch to operator.rst structuring it more clearly and adding examples to the "in-place" operations review
Messages (6)
msg115237 - (view) Author: Arnaud Delobelle (arno) Date: 2010-08-30 18:49
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
msg115484 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-09-03 19:14
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.
msg115486 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2010-09-03 19:31
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.
msg115594 - (view) Author: Arnaud Delobelle (arno) Date: 2010-09-04 18:14
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.
msg115598 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-09-04 18:31
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.
msg125774 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-01-08 10:27
See r87862.
History
Date User Action Args
2011-01-08 10:27:57rhettingersetstatus: open -> closed

messages: + msg125774
resolution: fixed
nosy: rhettinger, terry.reedy, arno, docs@python
2010-09-04 18:31:56terry.reedysetmessages: + msg115598
2010-09-04 18:14:06arnosetfiles: + operator_structured.diff

messages: + msg115594
2010-09-03 19:32:01rhettingersetassignee: docs@python -> rhettinger
2010-09-03 19:31:31rhettingersetnosy: + rhettinger
messages: + msg115486
2010-09-03 19:14:26terry.reedysetversions: + Python 3.1, Python 2.7, Python 3.2, - Python 3.3
nosy: + terry.reedy

messages: + msg115484

stage: patch review
2010-08-30 18:49:32arnocreate