Bad examples in documentation

[myreallycoolname]

BPO	16607
Nosy	@birkenfeld, @ezio-melotti, @durban

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2012-12-13.08:57:42.529>
created_at = <Date 2012-12-04.18:48:27.453>
labels = ['invalid', 'docs']
title = 'Bad examples in documentation'
updated_at = <Date 2012-12-13.16:53:57.994>
user = 'https://bugs.python.org/myreallycoolname'

bugs.python.org fields:

activity = <Date 2012-12-13.16:53:57.994>
actor = 'pacopablo'
assignee = 'docs@python'
closed = True
closed_date = <Date 2012-12-13.08:57:42.529>
closer = 'daniel.urban'
components = ['Documentation']
creation = <Date 2012-12-04.18:48:27.453>
creator = 'myreallycoolname'
dependencies = []
files = []
hgrepos = []
issue_num = 16607
keywords = []
message_count = 11.0
messages = ['176927', '176929', '176940', '176961', '176962', '176964', '177387', '177388', '177399', '177414', '177417']
nosy_count = 6.0
nosy_names = ['georg.brandl', 'ezio.melotti', 'daniel.urban', 'docs@python', 'myreallycoolname', 'pacopablo']
pr_nums = []
priority = 'normal'
resolution = 'not a bug'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue16607'
versions = ['Python 3.2']

[myreallycoolname]

The doumentation examples imn the tutorial in python3.2 are at lest in part invalid. I was having trouble understanding the documentation so I pulled out my pthony interperator and pluged in one of tyhe examples.
Just as I thought self was not defined.
You can't learn python if the docs are bad.
Please review the examples under classes to make sure they are all correct.

[durban]

Could you please point to a specific example which is incorrect? Thank you.

[birkenfeld]

I had a look and can't see an example in the "Classes" doc where self might not be defined. Please reopen with a concrete pointer if you think otherwise.

[myreallycoolname]

Sorry about that. You will unfortunatly have to wait as I'm not on a computer that has python installed currently.

----- Original Message -----
From: Daniel Urban
Sent: 12/04/12 02:00 PM
To: doark@mail.com
Subject: [bpo-16607] Bad examples in documentation

Daniel Urban added the comment:

Could you please point to a specific example which is incorrect? Thank you.

----------
nosy: +daniel.urban

---

Python tracker <report@bugs.python.org>
<http://bugs.python.org/issue16607\>

---

[myreallycoolname]

I'm no expert so I'm not sure which it is but try these:

>>> class Complex:
...     def __init__(self, realpart, imagpart):
...         self.r = realpart
...         self.i = imagpart
...

class Bag:
    def __init__(self):
        self.data = []
    def add(self, x):
        self.data.append(x)
    def addtwice(self, x):
        self.add(x)
        self.add(x)

If that's not it wait and I'll submit a new and better bug report or add to the existing one.

----- Original Message -----
From: myreallycoolname
Sent: 12/04/12 04:12 PM
To: doark@mail.com
Subject: [bpo-16607] Bad examples in documentation

myreallycoolname added the comment:

Sorry about that. You will unfortunatly have to wait as I'm not on a computer that has python installed currently.

> ----- Original Message -----
> From: Daniel Urban
> Sent: 12/04/12 02:00 PM
> To: doark@mail.com
> Subject: [bpo-16607] Bad examples in documentation
>
> Daniel Urban added the comment:
>
> Could you please point to a specific example which is incorrect? Thank you.
>
> ----------
> nosy: +daniel.urban
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue16607\>
> _______________________________________
>

----------

---

Python tracker <report@bugs.python.org>
<http://bugs.python.org/issue16607\>

---

[durban]

Both work fine.

[myreallycoolname]

I am updating my bug report unfortunatly I am unable to give you a specific link due to the fact that I can not find the python3.2 documentation online. I do assure you that the docs from my computer are for python3.2 (as I have no other docs installed.) To find the docs I'm complaining about go to the index select tutorial and click on the classes section. The bad code along with the start of the chapter it is located in and the trace backs follow. Please note that errors are cumulative. In other words if you use variable a and variable a has no value (not created deffined etc.) then every time you use it you will get an error. Code follows:

9.2.1. Scopes and Namespaces Example
This is an example demonstrating how to reference the different scopes and namespaces, and howglobal and nonlocal affect variable binding:

>>> def scope_test():
...     def do_local():
...         spam = "local spam"
...     def do_nonlocal():
...         nonlocal spam
...         spam = "nonlocal spam"
...     def do_global():
...         global spam
...         spam = "global spam"
... 
SyntaxError: no binding for nonlocal 'spam' found
>>>     spam = "test spam"
  File "<stdin>", line 1
    spam = "test spam"
    ^
IndentationError: unexpected indent
>>>     do_local()
  File "<stdin>", line 1
    do_local()
    ^
IndentationError: unexpected indent
>>>     print("After local assignment:", spam)
  File "<stdin>", line 1
    print("After local assignment:", spam)
    ^
IndentationError: unexpected indent
>>>     do_nonlocal()
  File "<stdin>", line 1
    do_nonlocal()
    ^
IndentationError: unexpected indent
>>>     print("After nonlocal assignment:", spam)
  File "<stdin>", line 1
    print("After nonlocal assignment:", spam)
    ^
IndentationError: unexpected indent
>>>     do_global()
  File "<stdin>", line 1
    do_global()
    ^
IndentationError: unexpected indent
>>>     print("After global assignment:", spam)
  File "<stdin>", line 1
    print("After global assignment:", spam)
    ^
IndentationError: unexpected indent
>>> 
>>> scope_test()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'scope_test' is not defined
>>> print("In global scope:", spam)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'spam' is not defined

9.3.3. Instance Objects
Now what can we do with instance objects? The only operations understood by instance objects are attribute references. There are two kinds of valid attribute names, data attributes and methods.
data attributes correspond to “instance variables” in Smalltalk, and to “data members” in C++. Data attributes need not be declared; like local variables, they spring into existence when they are first assigned to. For example, if x is the instance of MyClass created above, the following piece of code will print the value 16, without leaving a trace:

>>> x.counter = 1
>>> while x.counter < 10:
...     x.counter = x.counter * 2
... print(x.counter)
  File "<stdin>", line 3
    print(x.counter)
        ^
SyntaxError: invalid syntax
>>> del x.counter

9.9. Iterators
By now you have probably noticed that most container objects can be looped over using a forstatement:

>>> for element in [1, 2, 3]:
...     print(element)
... for element in (1, 2, 3):
  File "<stdin>", line 3
    for element in (1, 2, 3):
      ^
SyntaxError: invalid syntax
>>>     print(element)
  File "<stdin>", line 1
    print(element)
    ^
IndentationError: unexpected indent
>>> for key in {'one':1, 'two':2}:
...     print(key)
... for char in "123":
  File "<stdin>", line 3
    for char in "123":
      ^
SyntaxError: invalid syntax
>>>     print(char)
  File "<stdin>", line 1
    print(char)
    ^
IndentationError: unexpected indent
>>> for line in open("myfile.txt"):
...     print(line)
... 
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
IOError: [Errno 2] No such file or directory: 'myfile.txt'
>>> 

This is one html page of errors not just one section. You may also want to check the python 3.3 docs for these errors.

[pacopablo]

The documentation is correct. The problem that you seem to be having are due to copy and pasting in the interpreter.

The source of you first error is that after you copy

>>> def scope_test():
...     def do_local():
...         spam = "local spam"
...     def do_nonlocal():
...         nonlocal spam
...         spam = "nonlocal spam"
...     def do_global():
...         global spam
...         spam = "global spam"
... 

into the interpreter, you press enter and the blank line tells the interpreter that you're done defining the class. However, if you look at the docs, the following statements:

    spam = "test spam"
    do_local()
    print("After local assignment:", spam)
    do_nonlocal()
    print("After nonlocal assignment:", spam)
    do_global()
    print("After global assignment:", spam)

are supposed to be part of the class. A similar issue exists for the issues you're experiencing with the loops. Except it's the opposite. In this case:

>>> for element in [1, 2, 3]:
...     print(element)
... for element in (1, 2, 3):
  File "<stdin>", line 3
    for element in (1, 2, 3):
      ^
SyntaxError: invalid syntax

the interpreter is expecting a blank line after the print statement to indicate that the loop is done. Since the second loop starts on the lien after "print", it thinks there is an indentation error.

[durban]

As John Hampton have explained it, the documentation is actually correct.