[ python-Bugs-1168135 ] Python 2.5a0 Tutorial errors and observations

[SourceForge.net]

Bugs item #1168135, was opened at 2005-03-22 01:58
Message generated for change (Settings changed) made by rhettinger
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1168135&group_id=5470

Category: Documentation
Group: Python 2.5
Status: Open
Resolution: None
Priority: 5
Submitted By: Michael R Bax (mrbax)
>Assigned to: Raymond Hettinger (rhettinger)
Summary: Python 2.5a0 Tutorial errors and observations

Initial Comment:
Please find attached my updated list of errors and 
observations in response to Python 2.5a0.

----------------------------------------------------------------------

Comment By: Terry J. Reedy (tjreedy)
Date: 2005-03-30 16:01

Message:
Logged In: YES 
user_id=593130

Subject to reading that particular version (.5a0), I generally 
agree with your suggestions.  Here are some specific comments 
on your comments.  Feel free to incorporate them into a revised 
suggestion list if you wish.

-----------
Your first correction is wrong.  -ly adverbs are never hyphenated 
(Chicago Manual of Style, Table 6.1, for instance).

-----------
3.1.2
>>> word[:1] = 'Splat'
	-- This is trying to assign 5 letters to one?

Slice assignment is replacement, not overwriting.  This is 
replacing 1 byte with 5, which *is* valid, and perhaps the point 
being made.  Perhaps you would recommend another change to 
be clearer?

-----------
##5.1.3
##Combining these two special cases, we see that "map(None, 
list1, list2)" is a convenient way of turning a pair of lists into a list 
of pairs
#	-- Shouldn't one rather use zip()?

I would agree that 'convenient' should be removed and a note 
added that this has been superceded by zip unless one wants 
the different behavior of extending shorter sequences.

----------
5.1.3
filter(function, sequence)" returns a sequence (of the same type, 
if possible)
	-- How could this ever be impossible?

I suppose a broken class, but then what would filter do?  If 
filter 'works' for all builtins, I agree that we should just say so.  
Perhaps 'returns a sequence of the same type (for all builtins 
and sensible user classes)' -- if that is true

--------
5.2
There is a way to remove an item from a list given its index 
instead of its value: the del statement. 
	-- How is this different to pop?

pop, builtin on top of del, also saves and returns the deleted value 
so it can be bound to something, which takes longer.  ie
def pop(self, i):
  ret = self[i]
  del self[i]
  return ret

----------------------------
5.3
Sequence unpacking requires that the list of variables on the left 
have the same number of elements as the length of the sequence
	-- requires that the list of variables on the left has 
(grammar)
	-- requires the list of variables on the left to have 
(alternate)

Since the code sequence on the left is not a Python list but only 
a common-meaning list, I think even better would be
"Sequence unpacking requires that the number of variables on 
the left be the same as the length of the sequence on the right"

------------------
5.7
Comparisons may be combined by the Boolean operators and 
and or
	-- combined using the (style)

In general, the return value of a short-circuit operator, when 
used as a general value and not as a Boolean, is the last 
evaluated argument. 
	-- rewrite: When used as a general value and not as a 
Boolean, the return value of a short-circuit operator is the last 
evaluated argument.

I would personally be a bit more radical here.  As has been said 
often on c.l.p in response to newby misconceptions about 'and' 
and 'or', they are not operators, in the sense of syntactically 
abbreviating function calls, but flow-control keywords 
abbreviating if-else constructs.  Saying so in the tutorial 
might 'short-circuit' some of the misconceptions.

-------------
9
a derived class can override any methods of its base class or 
classes, a method can call the method of a base class with the 
same name.
	-- classes, and a method (last phrase in a list)

There are no special constructors or destructors.
	-- What about __init__, or is that a "normal" 
constructor?

The special method __new__ constructs (and initializes 
immutables) (so why isn't it a 'special constructor'?), __init__ 
initializes,  But as I remember, the quoted sentence does seem 
confusing.

---------------
9.2
Otherwise, all variables found outside of the innermost scope are 
read-only.
	-- Explain what happens when you try to assign to a 
read-only variable?

You create a new local of the same name and will not be able to 
read the masked variable.

------------
9.8
raise Class, instance
	-- What's the point?  In the example thereafter, these 
three have the same effect:
		raise c()
		raise B, c()

raise instance
	-- wasn't this "new form" covered in 8.5 (raise MyClass
(2*2))?

I personally agree that the tutorial should emphasize the newest 
form (raise instance) and only mention back-compatible forms in 
passing.

...
- What is an example of an exception that is NOT a class?

Last I knew, strings are still legal, though deprecated.

-------------
9.11
sum(i*i for i in range(10))
	-- Why does this work?! 

because generator expressions require their own parentheses 
*unless* already directly enclosed by function-call parens.  I 
agree that this nice quirk should be explained,

-------------
B.1
...
>>> 7205759403792794L * 10L**30 / 2L**56
	-- The "L" extension does not appear to be necessary 
for the input -- why is it used?

Used to be needed before int-long unification.  I agree that 
tutorial should be updated to future-oriented present.

----------
C
The socket module uses the functions, getaddrinfo, and 
getnameinfo
	-- remove comma after "functions" [grammar]

and after getaddrinfo

-------------





----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1168135&group_id=5470