[issue16607] Bad examples in documentation
New submission from 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. ---------- assignee: docs@python components: Documentation messages: 176927 nosy: docs@python, myreallycoolname priority: normal severity: normal status: open title: Bad examples in documentation versions: Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
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> _______________________________________
Georg Brandl added the comment: 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. ---------- nosy: +georg.brandl resolution: -> invalid status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
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.
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
myreallycoolname added the comment: I'm no expert so I'm not sure which it is but try these:
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.
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
Daniel Urban added the comment: Both work fine. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
myreallycoolname added the comment: 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:
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:
9.9. Iterators By now you have probably noticed that most container objects can be looped over using a forstatement:
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. ---------- status: closed -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
John Hampton added the comment: 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
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:
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. ---------- nosy: +pacopablo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
Daniel Urban added the comment: As John Hampton have explained it, the documentation is actually correct. ---------- status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti stage: -> committed/rejected _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
myreallycoolname added the comment: Ok, but perhaps in order to aviod confusion the documentation could be changed so that the examples are complete or have an additional new line as needed. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
John Hampton added the comment: Ok, but perhaps in order to aviod confusion the documentation could be changed so that the examples are complete or have an additional new line as needed. Well, they are complete. And it's only an issue with the interpreter. If you were to copy and paste the examples into a file, say example.py, and run that with python via: python example.py then they would work as they are supposed to. If you backup in the tutorial to: http://docs.python.org/3/tutorial/interpreter.html#interactive-mode You will read an explanation of the interpreter prompts. It may be that there is a way to make it clearer, but to update those examples would require similar adjustments all over the docs. It would also only benefit the case where one were trying to run the code in the interpreter, and would make it more annoying to copy and paste into a file. So, I don't think changing anything is worth it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
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> _______________________________________
Georg Brandl added the comment: 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. ---------- nosy: +georg.brandl resolution: -> invalid status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
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.
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
myreallycoolname added the comment: I'm no expert so I'm not sure which it is but try these:
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.
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
Daniel Urban added the comment: Both work fine. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
myreallycoolname added the comment: 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:
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:
9.9. Iterators By now you have probably noticed that most container objects can be looped over using a forstatement:
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. ---------- status: closed -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
John Hampton added the comment: 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
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:
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. ---------- nosy: +pacopablo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
Daniel Urban added the comment: As John Hampton have explained it, the documentation is actually correct. ---------- status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti stage: -> committed/rejected _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
myreallycoolname added the comment: Ok, but perhaps in order to aviod confusion the documentation could be changed so that the examples are complete or have an additional new line as needed. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
John Hampton added the comment: Ok, but perhaps in order to aviod confusion the documentation could be changed so that the examples are complete or have an additional new line as needed. Well, they are complete. And it's only an issue with the interpreter. If you were to copy and paste the examples into a file, say example.py, and run that with python via: python example.py then they would work as they are supposed to. If you backup in the tutorial to: http://docs.python.org/3/tutorial/interpreter.html#interactive-mode You will read an explanation of the interpreter prompts. It may be that there is a way to make it clearer, but to update those examples would require similar adjustments all over the docs. It would also only benefit the case where one were trying to run the code in the interpreter, and would make it more annoying to copy and paste into a file. So, I don't think changing anything is worth it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16607> _______________________________________
participants (5)
-
Daniel Urban -
Ezio Melotti
-
Georg Brandl
-
John Hampton
-
myreallycoolname