| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="ref.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="ref.html" title='Python Reference Manual' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='index' href='genindex.html' title='Index' /> |
| 10 | <link rel='last' href='about.html' title='About this document...' /> |
| 11 | <link rel='help' href='about.html' title='About this document...' /> |
| 12 | <link rel="prev" href="slicings.html" /> |
| 13 | <link rel="parent" href="primaries.html" /> |
| 14 | <link rel="next" href="power.html" /> |
| 15 | <meta name='aesop' content='information' /> |
| 16 | <title>5.3.4 Calls</title> |
| 17 | </head> |
| 18 | <body> |
| 19 | <DIV CLASS="navigation"> |
| 20 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 21 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 22 | <tr> |
| 23 | <td class='online-navigation'><a rel="prev" title="5.3.3 Slicings" |
| 24 | href="slicings.html"><img src='../icons/previous.png' |
| 25 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 26 | <td class='online-navigation'><a rel="parent" title="5.3 Primaries" |
| 27 | href="primaries.html"><img src='../icons/up.png' |
| 28 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 29 | <td class='online-navigation'><a rel="next" title="5.4 The power operator" |
| 30 | href="power.html"><img src='../icons/next.png' |
| 31 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 32 | <td align="center" width="100%">Python Reference Manual</td> |
| 33 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 34 | href="contents.html"><img src='../icons/contents.png' |
| 35 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 36 | <td class='online-navigation'><img src='../icons/blank.png' |
| 37 | border='0' height='32' alt='' width='32' /></td> |
| 38 | <td class='online-navigation'><a rel="index" title="Index" |
| 39 | href="genindex.html"><img src='../icons/index.png' |
| 40 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 41 | </tr></table> |
| 42 | <div class='online-navigation'> |
| 43 | <b class="navlabel">Previous:</b> |
| 44 | <a class="sectref" rel="prev" href="slicings.html">5.3.3 Slicings</A> |
| 45 | <b class="navlabel">Up:</b> |
| 46 | <a class="sectref" rel="parent" href="primaries.html">5.3 Primaries</A> |
| 47 | <b class="navlabel">Next:</b> |
| 48 | <a class="sectref" rel="next" href="power.html">5.4 The power operator</A> |
| 49 | </div> |
| 50 | <hr /></div> |
| 51 | </DIV> |
| 52 | <!--End of Navigation Panel--> |
| 53 | |
| 54 | <H2><A NAME="SECTION007340000000000000000"></A><A NAME="calls"></A> |
| 55 | <a id='l2h-386' xml:id='l2h-386'></a> |
| 56 | <BR> |
| 57 | 5.3.4 Calls |
| 58 | </H2> |
| 59 | |
| 60 | <P> |
| 61 | A call calls a callable object (e.g., a function) with a possibly empty |
| 62 | series of arguments: |
| 63 | <a id='l2h-387' xml:id='l2h-387'></a> |
| 64 | <P> |
| 65 | <dl><dd class="grammar"> |
| 66 | <div class="productions"> |
| 67 | <table> |
| 68 | <tr> |
| 69 | <td><a id='tok-call' xml:id='tok-call'>call</a></td> |
| 70 | <td>::=</td> |
| 71 | <td><a class='grammartoken' href="primaries.html#tok-primary">primary</a> "(" [<a class='grammartoken' href="calls.html#tok-argument_list">argument_list</a> [","]] ")"</td></tr> |
| 72 | <a class='grammartoken' href="primaries.html#tok-primary">primary</a> "(" [<a class='grammartoken' href="calls.html#tok-argument_list">argument_list</a> [","] | |
| 73 | <a class='grammartoken' href="lists.html#tok-test">test</a> <a class='grammartoken' href="genexpr.html#tok-genexpr_for">genexpr_for</a> ] ")" |
| 74 | <tr> |
| 75 | <td><a id='tok-argument_list' xml:id='tok-argument_list'>argument_list</a></td> |
| 76 | <td>::=</td> |
| 77 | <td><a class='grammartoken' href="calls.html#tok-positional_arguments">positional_arguments</a> ["," <a class='grammartoken' href="calls.html#tok-keyword_arguments">keyword_arguments</a>]</td></tr> |
| 78 | <tr> |
| 79 | <td></td> |
| 80 | <td></td> |
| 81 | <td><code> ["," "*" <a class='grammartoken' href="Booleans.html#tok-expression">expression</a>]</code></td></tr> |
| 82 | <tr> |
| 83 | <td></td> |
| 84 | <td></td> |
| 85 | <td><code> ["," "**" <a class='grammartoken' href="Booleans.html#tok-expression">expression</a>]</code></td></tr> |
| 86 | <tr> |
| 87 | <td></td> |
| 88 | <td></td> |
| 89 | <td><code>| <a class='grammartoken' href="calls.html#tok-keyword_arguments">keyword_arguments</a> ["," "*" <a class='grammartoken' href="Booleans.html#tok-expression">expression</a>]</code></td></tr> |
| 90 | <tr> |
| 91 | <td></td> |
| 92 | <td></td> |
| 93 | <td><code> ["," "**" <a class='grammartoken' href="Booleans.html#tok-expression">expression</a>]</code></td></tr> |
| 94 | <tr> |
| 95 | <td></td> |
| 96 | <td></td> |
| 97 | <td><code>| "*" <a class='grammartoken' href="Booleans.html#tok-expression">expression</a> ["," "**" <a class='grammartoken' href="Booleans.html#tok-expression">expression</a>]</code></td></tr> |
| 98 | <tr> |
| 99 | <td></td> |
| 100 | <td></td> |
| 101 | <td><code>| "**" <a class='grammartoken' href="Booleans.html#tok-expression">expression</a></code></td></tr> |
| 102 | <tr> |
| 103 | <td><a id='tok-positional_arguments' xml:id='tok-positional_arguments'>positional_arguments</a></td> |
| 104 | <td>::=</td> |
| 105 | <td><a class='grammartoken' href="Booleans.html#tok-expression">expression</a> ("," <a class='grammartoken' href="Booleans.html#tok-expression">expression</a>)*</td></tr> |
| 106 | <tr> |
| 107 | <td><a id='tok-keyword_arguments' xml:id='tok-keyword_arguments'>keyword_arguments</a></td> |
| 108 | <td>::=</td> |
| 109 | <td><a class='grammartoken' href="calls.html#tok-keyword_item">keyword_item</a> ("," <a class='grammartoken' href="calls.html#tok-keyword_item">keyword_item</a>)*</td></tr> |
| 110 | <tr> |
| 111 | <td><a id='tok-keyword_item' xml:id='tok-keyword_item'>keyword_item</a></td> |
| 112 | <td>::=</td> |
| 113 | <td><a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a> "=" <a class='grammartoken' href="Booleans.html#tok-expression">expression</a></td></tr> |
| 114 | </table> |
| 115 | </div> |
| 116 | <a class="grammar-footer" |
| 117 | href="grammar.txt" type="text/plain" |
| 118 | >Download entire grammar as text.</a> |
| 119 | </dd></dl> |
| 120 | |
| 121 | <P> |
| 122 | A trailing comma may be present after the positional and keyword |
| 123 | arguments but does not affect the semantics. |
| 124 | |
| 125 | <P> |
| 126 | The primary must evaluate to a callable object (user-defined |
| 127 | functions, built-in functions, methods of built-in objects, class |
| 128 | objects, methods of class instances, and certain class instances |
| 129 | themselves are callable; extensions may define additional callable |
| 130 | object types). All argument expressions are evaluated before the call |
| 131 | is attempted. Please refer to section <A href="function.html#function">7.5</A> for the syntax |
| 132 | of formal parameter lists. |
| 133 | |
| 134 | <P> |
| 135 | If keyword arguments are present, they are first converted to |
| 136 | positional arguments, as follows. First, a list of unfilled slots is |
| 137 | created for the formal parameters. If there are N positional |
| 138 | arguments, they are placed in the first N slots. Next, for each |
| 139 | keyword argument, the identifier is used to determine the |
| 140 | corresponding slot (if the identifier is the same as the first formal |
| 141 | parameter name, the first slot is used, and so on). If the slot is |
| 142 | already filled, a <tt class="exception">TypeError</tt> exception is raised. |
| 143 | Otherwise, the value of the argument is placed in the slot, filling it |
| 144 | (even if the expression is <code>None</code>, it fills the slot). When all |
| 145 | arguments have been processed, the slots that are still unfilled are |
| 146 | filled with the corresponding default value from the function |
| 147 | definition. (Default values are calculated, once, when the function |
| 148 | is defined; thus, a mutable object such as a list or dictionary used |
| 149 | as default value will be shared by all calls that don't specify an |
| 150 | argument value for the corresponding slot; this should usually be |
| 151 | avoided.) If there are any unfilled slots for which no default value |
| 152 | is specified, a <tt class="exception">TypeError</tt> exception is raised. Otherwise, |
| 153 | the list of filled slots is used as the argument list for the call. |
| 154 | |
| 155 | <P> |
| 156 | If there are more positional arguments than there are formal parameter |
| 157 | slots, a <tt class="exception">TypeError</tt> exception is raised, unless a formal |
| 158 | parameter using the syntax "<tt class="samp">*identifier</tt>" is present; in this |
| 159 | case, that formal parameter receives a tuple containing the excess |
| 160 | positional arguments (or an empty tuple if there were no excess |
| 161 | positional arguments). |
| 162 | |
| 163 | <P> |
| 164 | If any keyword argument does not correspond to a formal parameter |
| 165 | name, a <tt class="exception">TypeError</tt> exception is raised, unless a formal |
| 166 | parameter using the syntax "<tt class="samp">**identifier</tt>" is present; in this |
| 167 | case, that formal parameter receives a dictionary containing the |
| 168 | excess keyword arguments (using the keywords as keys and the argument |
| 169 | values as corresponding values), or a (new) empty dictionary if there |
| 170 | were no excess keyword arguments. |
| 171 | |
| 172 | <P> |
| 173 | If the syntax "<tt class="samp">*expression</tt>" appears in the function call, |
| 174 | "<tt class="samp">expression</tt>" must evaluate to a sequence. Elements from this |
| 175 | sequence are treated as if they were additional positional arguments; |
| 176 | if there are postional arguments <var>x1</var>,...,<var>xN</var> , and |
| 177 | "<tt class="samp">expression</tt>" evaluates to a sequence <var>y1</var>,...,<var>yM</var>, this |
| 178 | is equivalent to a call with M+N positional arguments |
| 179 | <var>x1</var>,...,<var>xN</var>,<var>y1</var>,...,<var>yM</var>. |
| 180 | |
| 181 | <P> |
| 182 | A consequence of this is that although the "<tt class="samp">*expression</tt>" syntax |
| 183 | appears <em>after</em> any keyword arguments, it is processed |
| 184 | <em>before</em> the keyword arguments (and the |
| 185 | "<tt class="samp">**expression</tt>" argument, if any - see below). So: |
| 186 | |
| 187 | <P> |
| 188 | <div class="verbatim"><pre> |
| 189 | >>> def f(a, b): |
| 190 | ... print a, b |
| 191 | ... |
| 192 | >>> f(b=1, *(2,)) |
| 193 | 2 1 |
| 194 | >>> f(a=1, *(2,)) |
| 195 | Traceback (most recent call last): |
| 196 | File "<stdin>", line 1, in ? |
| 197 | TypeError: f() got multiple values for keyword argument 'a' |
| 198 | >>> f(1, *(2,)) |
| 199 | 1 2 |
| 200 | </pre></div> |
| 201 | |
| 202 | <P> |
| 203 | It is unusual for both keyword arguments and the |
| 204 | "<tt class="samp">*expression</tt>" syntax to be used in the same call, so in practice |
| 205 | this confusion does not arise. |
| 206 | |
| 207 | <P> |
| 208 | If the syntax "<tt class="samp">**expression</tt>" appears in the function call, |
| 209 | "<tt class="samp">expression</tt>" must evaluate to a (subclass of) dictionary, the |
| 210 | contents of which are treated as additional keyword arguments. In the |
| 211 | case of a keyword appearing in both "<tt class="samp">expression</tt>" and as an |
| 212 | explicit keyword argument, a <tt class="exception">TypeError</tt> exception is |
| 213 | raised. |
| 214 | |
| 215 | <P> |
| 216 | Formal parameters using the syntax "<tt class="samp">*identifier</tt>" or |
| 217 | "<tt class="samp">**identifier</tt>" cannot be used as positional argument slots or |
| 218 | as keyword argument names. Formal parameters using the syntax |
| 219 | "<tt class="samp">(sublist)</tt>" cannot be used as keyword argument names; the |
| 220 | outermost sublist corresponds to a single unnamed argument slot, and |
| 221 | the argument value is assigned to the sublist using the usual tuple |
| 222 | assignment rules after all other parameter processing is done. |
| 223 | |
| 224 | <P> |
| 225 | A call always returns some value, possibly <code>None</code>, unless it |
| 226 | raises an exception. How this value is computed depends on the type |
| 227 | of the callable object. |
| 228 | |
| 229 | <P> |
| 230 | If it is-- |
| 231 | |
| 232 | <P> |
| 233 | <DL> |
| 234 | <DT><STRONG>a user-defined function:</STRONG></DT> |
| 235 | <DD>The code block for the function is |
| 236 | executed, passing it the argument list. The first thing the code |
| 237 | block will do is bind the formal parameters to the arguments; this is |
| 238 | described in section <A href="function.html#function">7.5</A>. When the code block executes a |
| 239 | <tt class="keyword">return</tt> statement, this specifies the return value of the |
| 240 | function call. |
| 241 | <a id='l2h-388' xml:id='l2h-388'></a><a id='l2h-389' xml:id='l2h-389'></a><a id='l2h-390' xml:id='l2h-390'></a><a id='l2h-391' xml:id='l2h-391'></a> |
| 242 | <P> |
| 243 | </DD> |
| 244 | <DT><STRONG>a built-in function or method:</STRONG></DT> |
| 245 | <DD>The result is up to the |
| 246 | interpreter; see the <em class="citetitle"><a |
| 247 | href="../lib/built-in-funcs.html" |
| 248 | title="Python |
| 249 | Library Reference" |
| 250 | >Python |
| 251 | Library Reference</a></em> for the descriptions of built-in functions and |
| 252 | methods. |
| 253 | <a id='l2h-392' xml:id='l2h-392'></a><a id='l2h-393' xml:id='l2h-393'></a><a id='l2h-394' xml:id='l2h-394'></a><a id='l2h-395' xml:id='l2h-395'></a><a id='l2h-396' xml:id='l2h-396'></a><a id='l2h-397' xml:id='l2h-397'></a><a id='l2h-398' xml:id='l2h-398'></a><a id='l2h-399' xml:id='l2h-399'></a> |
| 254 | <P> |
| 255 | </DD> |
| 256 | <DT><STRONG>a class object:</STRONG></DT> |
| 257 | <DD>A new instance of that class is returned. |
| 258 | <a id='l2h-400' xml:id='l2h-400'></a><a id='l2h-401' xml:id='l2h-401'></a> |
| 259 | <P> |
| 260 | </DD> |
| 261 | <DT><STRONG>a class instance method:</STRONG></DT> |
| 262 | <DD>The corresponding user-defined |
| 263 | function is called, with an argument list that is one longer than the |
| 264 | argument list of the call: the instance becomes the first argument. |
| 265 | <a id='l2h-402' xml:id='l2h-402'></a><a id='l2h-403' xml:id='l2h-403'></a><a id='l2h-404' xml:id='l2h-404'></a> |
| 266 | <P> |
| 267 | </DD> |
| 268 | <DT><STRONG>a class instance:</STRONG></DT> |
| 269 | <DD>The class must define a <tt class="method">__call__()</tt> |
| 270 | method; the effect is then the same as if that method was called. |
| 271 | <a id='l2h-405' xml:id='l2h-405'></a><a id='l2h-407' xml:id='l2h-407'></a> |
| 272 | <P> |
| 273 | </DD> |
| 274 | </DL> |
| 275 | |
| 276 | <P> |
| 277 | |
| 278 | <DIV CLASS="navigation"> |
| 279 | <div class='online-navigation'> |
| 280 | <p></p><hr /> |
| 281 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 282 | <tr> |
| 283 | <td class='online-navigation'><a rel="prev" title="5.3.3 Slicings" |
| 284 | href="slicings.html"><img src='../icons/previous.png' |
| 285 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 286 | <td class='online-navigation'><a rel="parent" title="5.3 Primaries" |
| 287 | href="primaries.html"><img src='../icons/up.png' |
| 288 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 289 | <td class='online-navigation'><a rel="next" title="5.4 The power operator" |
| 290 | href="power.html"><img src='../icons/next.png' |
| 291 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 292 | <td align="center" width="100%">Python Reference Manual</td> |
| 293 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 294 | href="contents.html"><img src='../icons/contents.png' |
| 295 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 296 | <td class='online-navigation'><img src='../icons/blank.png' |
| 297 | border='0' height='32' alt='' width='32' /></td> |
| 298 | <td class='online-navigation'><a rel="index" title="Index" |
| 299 | href="genindex.html"><img src='../icons/index.png' |
| 300 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 301 | </tr></table> |
| 302 | <div class='online-navigation'> |
| 303 | <b class="navlabel">Previous:</b> |
| 304 | <a class="sectref" rel="prev" href="slicings.html">5.3.3 Slicings</A> |
| 305 | <b class="navlabel">Up:</b> |
| 306 | <a class="sectref" rel="parent" href="primaries.html">5.3 Primaries</A> |
| 307 | <b class="navlabel">Next:</b> |
| 308 | <a class="sectref" rel="next" href="power.html">5.4 The power operator</A> |
| 309 | </div> |
| 310 | </div> |
| 311 | <hr /> |
| 312 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 313 | </DIV> |
| 314 | <!--End of Navigation Panel--> |
| 315 | <ADDRESS> |
| 316 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 317 | </ADDRESS> |
| 318 | </BODY> |
| 319 | </HTML> |