Python Documentation (should be better?)

[Mike Meyer]

"Christopher J. Bottaro" <cjbottaro at alumni.cs.utexas.edu> writes:

> because there are no namespaces or classes, but still I think Python could
> do something similar.  Say for instance search for "append" and it will
> come back with a page for list's append, a page for array's append, etc.

A seperate page for each method of every class? Ouch. I think that's
serious overkill. Having the entries for the methods in the pages be
labelled, so that a search could return a direct link to the
appropriate paragraph, that would be a major improvement.

> If I wanted to learn about "types" in Python, where do I look?  The PHP
> manual has a whole section on the built-in types, how to get the type of a
> var, how to change cast the type of a var, etc.  I think that is such an
> important and basic part of any language, yet its scattered all over Python
> documention, difficult to find (i.e. not in a manual, but the library
> reference).

Python variables don't have types. Python objects have types. Python
further confuses the issue by overloading "types" to mean builtin
types, which are different classes, which can both instantiate as a
variable. If you're doing things Pythonically, you generally don't
care what type a variable has - you care that it supports the
operations you want. Changing the type of an object is either
impossible or dificult, depending on the object - and not to be
undertaken lightly.

What I'm trying to say is that "type" just isn't as important a
concept in Python as it is in other languages. PHP, for instance,
apparently has a number of automatic conversions between types if
various operations are applied, so you have to care what type an
object is or risk getting it converted accidently. Python doesn't do
that. Many languages have typed variables, so everything you do will
depend on the type of the variable. Python doesn't do that. Some OO
languages conflate types and classes, and use isinstane for type
checking. Python doesn't do that.  All that python cares about - and
all that you really need to care about - is that the object referenced
by the variable support the features you want to use.

> I guess what I'm trying to say is that there should be a "manual" which is
> half way between the tutorial and the library reference, that is organized
> more like a traditional manual (whatever that means, right?) and is more
> easily searchable.

Given that Python hides the difference between user-defined objects
and built-in objects, it's not clear to me that anything other than
the current system, with all the classes/types in one place, makes
sense.

That's not to say the documentation can't be improved. I'm just not
convinced that a "manual" pulling in parts from multiple different
places is an improvement.

That said, I'd like to ask what's wrong with the language reference?
It provides a nice reference on the syntax and semantics of the
language. What does the tutorial provide that you can't get from the
Language Reference?

         <mike
-- 
Mike Meyer <mwm at mired.org>			http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.