[docs] Python tutorial

[Richard Trahan]

I am a noob in Python (but not in programming), and am reading the
tutorial. Generally it is well-written, but section 6.4 on packages is
obscure. "Package" is not actually defined anywhere. The last two
paragraphs of this section are unclear. The terms module, submodule,
package, subpackage, item, and name are all very confusing. There is no
comprehensible explanation of __init__.py and how it affects the search for
modules.

Missing from the tutorial is a description of the most-used string
functions. The ones in the standard library are not the most common. Look
at the Java String API to see many functions which are not found in the
Python Standard Library in the tutorial.

I would like to see a large section on this web site dealing with the issue
of why almost nothing works as advertised in what is supposed to be a
simple computer language. Getting a Python program to work requires
numerous kludges found in countless blogs. For example, even on the first
execution of a module, the garbage collection system will wipe out an image
object before it is used in the very module in which it is created. I found
a blog which says the fix is to save the image object to a widget variable
There is no explanation of why this works. There are hundreds of tricks
like that all over the Internet, which are not explained in the tutorial or
any other official documentation.

There are also installation problems. Why does Ubuntu install version 2.7
from its Software Center? If 3.3 is downloaded explicitly, it doesn't work
with any version of IDLE or Spyder available on Ubuntu. These types of
issues are very annoying to someone just trying to learn the language.
There should be a section in the tutorial on all this.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20150603/5a3f7182/attachment.html>