GNU Info

(python2.1-ref.info)Calls

---

Prev: Slicings Up: Primaries

---

Enter node , (file) or (file)node

Calls
-----

A call calls a callable object (e.g., a function) with a possibly empty
series of arguments:

     call:                   primary "(" [argument_list [","]] ")"
     argument_list:          positional_arguments ["," keyword_arguments]
                           | keyword_arguments
     positional_arguments:   expression ("," expression)*
     keyword_arguments:      keyword_item ("," keyword_item)*
     keyword_item:           identifier "=" expression

A trailing comma may be present after an argument list but does not
affect the semantics.

The primary must evaluate to a callable object (user-defined functions,
built-in functions, methods of built-in objects, class objects, methods
of class instances, and certain class instances themselves are
callable; extensions may define additional callable object types).  All
argument expressions are evaluated before the call is attempted.
Please refer to section Note: Function definitions for the syntax of
formal parameter lists.

If keyword arguments are present, they are first converted to
positional arguments, as follows.  First, a list of unfilled slots is
created for the formal parameters.  If there are N positional
arguments, they are placed in the first N slots.  Next, for each
keyword argument, the identifier is used to determine the corresponding
slot (if the identifier is the same as the first formal parameter name,
the first slot is used, and so on).  If the slot is already filled, a
`TypeError' exception is raised.  Otherwise, the value of the argument
is placed in the slot, filling it (even if the expression is `None', it
fills the slot).  When all arguments have been processed, the slots
that are still unfilled are filled with the corresponding default value
from the function definition.  (Default values are calculated, once,
when the function is defined; thus, a mutable object such as a list or
dictionary used as default value will be shared by all calls that don't
specify an argument value for the corresponding slot; this should
usually be avoided.)  If there are any unfilled slots for which no
default value is specified, a `TypeError' exception is raised.
Otherwise, the list of filled slots is used as the argument list for
the call.

If there are more positional arguments than there are formal parameter
slots, a `TypeError' exception is raised, unless a formal parameter
using the syntax `*identifier' is present; in this case, that formal
parameter receives a tuple containing the excess positional arguments
(or an empty tuple if there were no excess positional arguments).

If any keyword argument does not correspond to a formal parameter name,
a `TypeError' exception is raised, unless a formal parameter using the
syntax `**identifier' is present; in this case, that formal parameter
receives a dictionary containing the excess keyword arguments (using
the keywords as keys and the argument values as corresponding values),
or a (new) empty dictionary if there were no excess keyword arguments.

Formal parameters using the syntax `*identifier' or `**identifier'
cannot be used as positional argument slots or as keyword argument
names.  Formal parameters using the syntax `(sublist)' cannot be used
as keyword argument names; the outermost sublist corresponds to a
single unnamed argument slot, and the argument value is assigned to the
sublist using the usual tuple assignment rules after all other
parameter processing is done.

A call always returns some value, possibly `None', unless it raises an
exception.  How this value is computed depends on the type of the
callable object.

If it is--

`a user-defined function:'
     The code block for the function is executed, passing it the
     argument list.  The first thing the code block will do is bind the
     formal parameters to the arguments; this is described in section
     Note: Function definitions.  When the code block executes a
     `return' statement, this specifies the return value of the
     function call.

`a built-in function or method:'
     The result is up to the interpreter; see the  for the descriptions
     of built-in functions and methods.

`a class object:'
     A new instance of that class is returned.

`a class instance method:'
     The corresponding user-defined function is called, with an
     argument list that is one longer than the argument list of the
     call: the instance becomes the first argument.

`a class instance:'
     The class must define a `__call__()' method; the effect is then
     the same as if that method was called.