Could someone please paraphrase this statement about variables and functions in Python?

[Neil Cerutti]

On 2013-09-05, jsrig88 at gmail.com <jsrig88 at gmail.com> wrote:
> I am going through the tutorials on docs.python.org, and I came
> across this excerpt from
> http://docs.python.org/3/tutorial/controlflow.html:
>
> "The execution of a function introduces a new symbol table used
> for the local variables of the function. More precisely, all
> variable assignments in a function store the value in the local
> symbol table; whereas variable references first look in the
> local symbol table, then in the local symbol tables of
> enclosing functions, then in the global symbol table, and
> finally in the table of built-in names. Thus, global variables
> cannot be directly assigned a value within a function (unless
> named in a global statement), although they may be referenced.

Every function has its own scope, which is a list of its local
variables.

When you assign to a local name in a function, you are assigning
to the symbol table that stores those variables.

Not spelled out exactly is that every unqualified name assigned
to in a function is assumed to be a local variable. So this is an
error:

>>> x = 5
>>> def foo():
...   print(x)
...   x = 7
...
>>> foo()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 2, in foo
UnboundLocalError: local variable 'x' referenced before assignment

If the assignement to x is removed, then you can refer to the
global variable just fine.

>>> x = 5
>>> def foo():
...   print(x)
...
>>> foo()
5

In a function, you can allow assignment to global variables using
the global statement.

>>> x = 5
>>> def foo():
...   global x
...   print(x)
...   x = 7
...
>>> foo()
5
>>> x
7

> "The actual parameters (arguments) to a function call are
> introduced in the local symbol table of the called function
> when it is called; thus, arguments are passed using call by
> value (where the value is always an object reference, not the
> value of the object). [1] When a function calls another
> function, a new local symbol table is created for that call."

When you call a function, it is as if an assignment of the
arguments to the function paramters takes place.

def foo(x, y):
  print(x, y)

When I call foo(1, 2), the effect is:

1. The local variable x is assigned to the object returned by the
   expression 1
2. The local y is assigned to the object returned by the expression 2
3. The body of function foo is run.

Assignments in Python are name-binding.  Objects are passed into
functions by assignment. If you understand how assignment works
in Python, that's a good explanation.

Finally, every time you call a function a new symbol table is
built. So I can do the following without names conflicting:

def foo(x, y):
   if x == 0:
     return y
   y *= 2
   return foo(x-1, y)

> Even as a professional programmer, I'm not really able to
> follow this.  It seems self-contradictory, amgiguous, and
> incomplete.  The problem with looking for this information
> elsewhere is that it's not going to be all in one spot like
> this half the time, and it's not going to be readily searchable
> on Google without more knowledge of what it's referring to.
> However this looks like something that's too important to
> overlook.

It's not ambiguous, self-contradictory or incomplete. But it's
very densely packed with information; perhaps it's too complete.

> I can tell it's referring to things like scope, pass-by-value,
> references, probably the call stack, etc., but it is written
> extremely poorly.  Translation please?  Thanks!

I don't think that's a fair criticism, but it might be too
technical for a language tutorial.

-- 
Neil Cerutti