The Python Lib Reference explains the pow() function in
section 2.1 like that:

>>>
pow(  	x, y[, z])
    Return x to the power y; if z is present, return x
to the power y, modulo z (computed more efficiently
than pow(x, y) % z). The arguments must have numeric
types. With mixed operand types, the coercion rules for
binary arithmetic operators apply. For int and long int
operands, the result has the same type as the operands
(after coercion) unless the second argument is
negative; in that case, all arguments are converted to
float and a float result is delivered. For example,
10**2 returns 100, but 10**-2 returns 0.01.
<<<

The problem is here that the notation 10**2 is used in
the example without prior explanation that it is
equivalent to pow(10,2). A newbie reading the docs in
linear order may not know this here (many other
languages write x^y instead of x**y). The notation x**y
is only introduced later in section 2.3.4.

I recommend adding a short remark to this paragraph
explaining that instead of writing pow(x,y) you can
also write x**y.

Logged In: YES 
user_id=80475

The Lib Reference is like an encylopaedia; it does not 
purport to avoid forward references and be read linearly 
start to finish.

Also, in this case the meaning is 100% clear from the 
context.  IOW, given a discussion about x raised to the y 
power and an expression "10**2 returns 100, but 10**-2 
returns 0.01", the meaning of the operator is self-evident.

Logged In: YES 
user_id=193957

I'm not sure about that. You are thinking too much from an
expert/insider point of view, not from a newbie/learner
point of view.

For newbies, this is not so clear. See for example:
http://groups.google.com/group/comp.lang.python/browse_frm/thread/c82eb3c3a6068b7d

Even if the reader understands what 10**2 is, it is still
not clear at this place whether this is a Python expression
or simply a mathematical notation, and whether pow(x,y)
behaves exactly like x**y or not.

I still think a short note like "Note that you can also
write x**y as an abbreviation for pow(x,y)." makes all of
this clear and may be a help or a hint for newbies and
non-mathematicians.

Your argument that the Lib reference is not meant to be read
like a novel is true, but the introduction says explicitely
that reading it as a novel *is* an option, and encourages
people to read at least chapter 2 which is actually one of
the core parts of the whole Python documentation. So I think
many newbies will read the Tutorial (where the equivalence
of x**y and pow(x,y) is not mentioned either) and then at
least chapter 2 from the Lib reference. And even if you take
it only as a reference and just read the explanation of
pow() it may be a good reminder that pow(x,y) is actually
the same as x**y.

Logged In: YES 
user_id=193957

Now I understand why the Lib Reference suddenly uses the **
notation when it speaks about the pow() function: The
passage has been simply copied over to the Lib Reference
from section 5.4 of the Lang Reference about the ** operator.

By the way, this section 5.4 in the Lang reference mentions
the pow() function as well. So I think it would be only
consequent if the Lib reference about pow() reciprocates
that and refers to the power operator in turn.

Anyway, somebody has changed it in the SVN already; I think
it is now ok and hope you agree.