[docs] Bug in Python Tutorial

[Sandro Tosi]

Hello Jeff,
Thanks for your email. Please note that this mailing list is about
bugs in Python documentation, while it seems your seeking some
guidance and a first kick start in Python programming, and so
python-list is probably the best place for you. Anyhow, I'll try to
give my point-of-view, it might help you nonetheless.

On Fri, Dec 23, 2011 at 08:09, Jeff Mullen <jmullen10 at rochester.rr.com> wrote:
> The body of the loop is indented: indentation is Python’s way of grouping
> statements. Python does not (yet!) provide an intelligent input line editing
> facility, so you have to type a tab or space(s) for each indented line. In
> practice you will prepare more complicated input for Python with a text
> editor; most text editors have an auto-indent facility. When a compound
> statement is entered interactively, it must be followed by a blank line to
> indicate completion (since the parser cannot guess when you have typed the
> last line). Note that each line within a basic block must be indented by the
> same amount.

Ok, this paragraph mixes some tips for entering code in the python
interactive shell and how to group up statements, but it's very clear
about how to group them up: with indentation. statements at the same
indentation level belongs to the same code block.

1 for i in range(10):
2     print i
3     print 2*i
4     for j in range(10):
5         print j

in this small example, line 1 is the first line, below that there's
its code block composed by line 2 and 3 (print statements) and a block
made of line 4-5; line 4 is another for loop which requires a
sub-block of code, composed by only line 5.

Lines 2-4 are indented more than line 1 because the are the for code
block, so they are "nested" below it. the same holds for line 5 in
respect to line 4.


> Loop statements may have an else clause; it is executed when the loop
> terminates through exhaustion of the list (with for) or when the condition
> becomes false (with while), but not when the loop is terminated by a break
> statement. This is exemplified by the following loop, which searches for
> prime numbers:
>>>>
>
>>>> for n in range(2, 10):
> ... for x in range(2, n):
> ... if n % x == 0:
> ... print n, 'equals', x, '*', n/x
> ... break
> ... else:
> ... # loop fell through without finding a factor
> ... print n, 'is a prime number'
> ...
> 2 is a prime number
> 3 is a prime number
> 4 equals 2 * 2
> 5 is a prime number
> 6 equals 2 * 3
> 7 is a prime number
> 8 equals 2 * 4
> 9 equals 3 * 3
>
> (Yes, this is the correct code. Look closely: the else clause belongs to the
> for loop, not the if statement.)
>
> ------------------------
>
> This is not sufficient to show me how to code in Python.

But this is not what you asked in the first part of teh email: you
were looking for information about code block and indentation. for
this task, I find http://docs.python.org/tutorial/index.html quiet
complete.

> Note in the last
> sentence, it says that the else clause groups with the for statement, not
> the if statement. It does not, however, explain why.

It's explained before the code example (and also reported in the text
you cut&pasted in the email): Loop statements may have an else clause;
it is executed when the loop terminates through exhaustion of the list
(with for) or when the condition becomes false (with while), but not
when the loop is terminated by a break  statement.

> Nor does the document
> anywhere explain how statements are grouped in Python.

this part talks about just one aspect of Python language, but the code
block definition is already described in section 3.2, that you cited.

> The best I can come
> up with is that the compiler itself uses the indentation level to make this
> determination

except it's an interpreter :) yes, it's the indentation that matters
to identify code block.

> which strikes me as rather kludgy, as indentation level is
> something that different people often have different interpretations of.

Well, every programming language has its syntax and semantics, for
Python indentation matters, nothing more nothing less.

> Can you clear up my confusion?

I hope it's clear now, else please point to specific aspects that are
still a bit foggy.

Regards,
-- 
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi