Document assignment syntax

[eschnett]

I believe the documentation does not describe the syntax of the assignment operator. From examples, I know that e.g.

a,b = 1,2

is possible. However, I don't know whether this is a special syntax for assignment, or whether LHS and RHS are implicitly interpreted as tuples.

I found out the hard way that writing

(a,b) = x

interprets x as iterable, leading to a very strange error about a method "start" when x returns a value that is not iterable. Apparently, assignment to a tuple can automatically convert e.g. from lists -- naively, I would have expected that I have to call a function for this.

I also found out that

(a,) = (1,2)

is possible, and silently discards the additional value. I would have expected a warning in this case.

Finally, I somehow expected that "_" (using an underscore as variable name) is a placeholder that I can use to discard values, as in

(a,_) = (1,2)

However, this instead creates a local variable called "_".

Since I did not expect these behaviours, others may be surprised as well. It would be good to describe them in the documentation.

[JeffBezanson]

You're right, the full behavior of multiple assignment from iterators is not documented. That should be remedied.

It's slightly open to interpretation whether "reading the whole manual" or "just trying it" counts as "the hard way" to find something out :)

[elextr]

"Just trying it" is often the way I find the "wrong way"™ to do it :)

[pao]

However, this instead creates a local variable called "_".

I had discussed this previously with @StefanKarpinski--to summarize, there's not really a reason not to make the assignment, and _ is a legal identifier, so that's what it does. By convention, you would not proceed to use _ on the RHS of an expression.

[Moelf]

Do we know where would be a good place / keywords to document this?

[laborg]

This has been documented in #30745