Changes to the New Reference Manual

[Donald O'Donnell]

Hi all,

I've been programming in Python for about 2 months now (other languages
~ 25 yrs.) and really love it.  Currently porting a mainframe language
interpreter/editor to run on Windows.  (I wouldn't attempt this with any
other language.)

In order to learn about the new features in ver 2.0, I recently
downloaded the Python Reference Manual Release 2.0b1.1.  Here are some
of my thoughts on it.  (I hope I'm not being too nitpicky.)


Python Reference Manual
Release 2.0b1.1
September 12, 2000


>    5.2.4  List displays
><snip>
>    A list display yields a new list object. Its contents are 
>    specified by providing either a list of expressions or a 
>    list comprehension. ...
><snip>
>                                          ... When a list 
>    comprehension is supplied, it consists of a single expression
>    followed by at least one for clause and zero or more for or 
>    if clauses. In this case, the elements of the new list
>    are those that would be produced by considering each of the 
>    for or if clauses a block, nesting from left to right, and
>    evaluating the expression to produce a list element each 
>    time the innermost block is reached.

The above extract is a model of precision, clarity, and conciseness, in
keeping with the previous version of the manual.

BUT ...

>    5.9  Comparisons
><snip>
>
>    The operators in and not in test for set membership: every 
>    type can define membership in whatever way is appropriate.
>    Traditionally, this interface has been tightly bound the 
>    sequence interface, which is related in that presence in
>    a sequence can be usefully interpreted as membership in a 
>    set.

Confusing and clumsy, I think.  I needed several re-reads, interpolating
an apparently missing word, and trying different word emphasis, before
the meaning came clear.

>    For the list, tuple types, x in y is true if and only if 
>    there exists such an index i such that varx == y[i] is true.
>    
>    For the Unicode and string types, x in y is true if and only 
>    if there exists such an index i such that varx == y[i]
>    is true. 

... there exists an index i such that ... (one such is enough).  
What is "varx", shouldn't that be "x" in both cases?  


>    6.3.1  Augmented Assignment statements
>
<snip>
>    An augmented assignment evaluates the target (which, unlike 
>    with normal assignment statements, cannot be a tuple)
>    and the expression list, performs the binary operation 
>    specific to the type of assignment on the two operands, and
>    assigns the result to the original target. The target is 
>    only evaluated once.

"... which, unlike <with> normal assignment statements, cannot be a
tuple ..."

This extract (with the extra "with" removed to improve grammar) seems to
imply that augmented assignment does not support a tuple as a target
while normal assignment does.  This is just the reverse of what I
believed to be the case from what I've read on the c.l.p.  (Or do I have
it wrong?)


>    6.6  The print statement
>
<snip>
>    print also has an extended form, defined as
>
>       print_stmt: ’>>’ expression [ (’,’ expression)+ [’,’] ] )
>
>    In this form, the first expression after the >> must evaluate 
>    to a "file-like" object, specifically an object that has a
>    write() method as described above.

Two problems with this extract:
1.  The "print" part of the BNF notation is missing.
2.  Single quotes (') are used around literal syntax elements, 
whereas double quotes (") are used throughout the rest of the manual.


>    6.11  The import statement
>
<snip>
>    The first form of import statement binds the module name 
>    in the local namespace to the module object, and then
>    goes on to import the next identifier, if any. If the module 
>    name is followed by as, the name following as is used as
>    the local name for the module. To avoid confusion, you 
>    cannot import sub-modules ’as’ a different local name. So
>    ’import module as m’ is legal, but ’import module.submod 
>    as s’ is not. The latter should be written as ’from module
>    import submod as s’, see below.   

"... you cannot import sub-modules 'as' a different local name."

I don't believe the term "sub-module" is defined in the language.  It's
not listed in the index and a full text search finds only this reference
to it. A following section discusses hierarchical module names, which
use the same syntax, but with different semantics, i.e., package.module
not module.submod.

Later in the same section ...

>    The from form does not bind the module name: it goes 
>    through the list of identifiers, looks each one of them up
>    in the module found in step (1), and binds the name in the 
>    local namespace to the object thus found. Like with the
>    first form of import, an alternate local name can be 
>    supplied by specifying "as localname". 

"... Like with the first form of import, ..."

I suppose the old "as/like" controversy is a lost battle; even radio and
TV announcers are using "like" when the mean "as".  And I would be
willing to concede this point, except that when "like" is followed by
"with" it really grates on my ears (and "as with" is so much easier to
type ;-).

I know, I ought to be content that the syntax isn't 

        "import" module ["like" name] ...       <wink>


I hope I don't sound too critical, but I believe the quality of the
Python documentation has been excellent in the past, and I would hate to
see it become degraded, due to different priorities or lack of interest
or whatever, under its new roof.

well-meaningly,
- Don