| 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="next" href="class.html" /> |
| 13 | <link rel="prev" href="try.html" /> |
| 14 | <link rel="parent" href="compound.html" /> |
| 15 | <link rel="next" href="class.html" /> |
| 16 | <meta name='aesop' content='information' /> |
| 17 | <title>7.5 Function definitions</title> |
| 18 | </head> |
| 19 | <body> |
| 20 | <DIV CLASS="navigation"> |
| 21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 23 | <tr> |
| 24 | <td class='online-navigation'><a rel="prev" title="7.4 The try statement" |
| 25 | href="try.html"><img src='../icons/previous.png' |
| 26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 27 | <td class='online-navigation'><a rel="parent" title="7. Compound statements" |
| 28 | href="compound.html"><img src='../icons/up.png' |
| 29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 30 | <td class='online-navigation'><a rel="next" title="7.6 Class definitions" |
| 31 | href="class.html"><img src='../icons/next.png' |
| 32 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 33 | <td align="center" width="100%">Python Reference Manual</td> |
| 34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 35 | href="contents.html"><img src='../icons/contents.png' |
| 36 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 37 | <td class='online-navigation'><img src='../icons/blank.png' |
| 38 | border='0' height='32' alt='' width='32' /></td> |
| 39 | <td class='online-navigation'><a rel="index" title="Index" |
| 40 | href="genindex.html"><img src='../icons/index.png' |
| 41 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 42 | </tr></table> |
| 43 | <div class='online-navigation'> |
| 44 | <b class="navlabel">Previous:</b> |
| 45 | <a class="sectref" rel="prev" href="try.html">7.4 The try statement</A> |
| 46 | <b class="navlabel">Up:</b> |
| 47 | <a class="sectref" rel="parent" href="compound.html">7. Compound statements</A> |
| 48 | <b class="navlabel">Next:</b> |
| 49 | <a class="sectref" rel="next" href="class.html">7.6 Class definitions</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H1><A NAME="SECTION009500000000000000000"></A><A NAME="function"></A> |
| 56 | <BR> |
| 57 | 7.5 Function definitions |
| 58 | </H1> |
| 59 | <a id='l2h-606' xml:id='l2h-606'></a><a id='l2h-607' xml:id='l2h-607'></a> |
| 60 | <P> |
| 61 | A function definition defines a user-defined function object (see |
| 62 | section <A href="types.html#types">3.2</A>): |
| 63 | <a id='l2h-608' xml:id='l2h-608'></a><a id='l2h-609' xml:id='l2h-609'></a> |
| 64 | <P> |
| 65 | <dl><dd class="grammar"> |
| 66 | <div class="productions"> |
| 67 | <table> |
| 68 | <tr> |
| 69 | <td><a id='tok-funcdef' xml:id='tok-funcdef'>funcdef</a></td> |
| 70 | <td>::=</td> |
| 71 | <td>[<a class='grammartoken' href="function.html#tok-decorators">decorators</a>] "def" <a class='grammartoken' href="function.html#tok-funcname">funcname</a> "(" [<a class='grammartoken' href="function.html#tok-parameter_list">parameter_list</a>] ")" |
| 72 | ":" <a class='grammartoken' href="compound.html#tok-suite">suite</a></td></tr> |
| 73 | <tr> |
| 74 | <td><a id='tok-decorators' xml:id='tok-decorators'>decorators</a></td> |
| 75 | <td>::=</td> |
| 76 | <td><a class='grammartoken' href="function.html#tok-decorator">decorator</a>+</td></tr> |
| 77 | <tr> |
| 78 | <td><a id='tok-decorator' xml:id='tok-decorator'>decorator</a></td> |
| 79 | <td>::=</td> |
| 80 | <td>"@" <a class='grammartoken' href="function.html#tok-dotted_name">dotted_name</a> ["(" [<a class='grammartoken' href="calls.html#tok-argument_list">argument_list</a> [","]] ")"] NEWLINE</td></tr> |
| 81 | <tr> |
| 82 | <td><a id='tok-dotted_name' xml:id='tok-dotted_name'>dotted_name</a></td> |
| 83 | <td>::=</td> |
| 84 | <td><a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a> ("." <a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a>)*</td></tr> |
| 85 | <tr> |
| 86 | <td><a id='tok-parameter_list' xml:id='tok-parameter_list'>parameter_list</a></td> |
| 87 | <td>::=</td> |
| 88 | <td>(<a class='grammartoken' href="function.html#tok-defparameter">defparameter</a> ",")*</td></tr> |
| 89 | <tr> |
| 90 | <td></td> |
| 91 | <td></td> |
| 92 | <td><code>( "*" <a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a> [, "**" <a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a>]</code></td></tr> |
| 93 | <tr> |
| 94 | <td></td> |
| 95 | <td></td> |
| 96 | <td><code> | "**" <a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a></code></td></tr> |
| 97 | <tr> |
| 98 | <td></td> |
| 99 | <td></td> |
| 100 | <td><code> | <a class='grammartoken' href="function.html#tok-defparameter">defparameter</a> [","] )</code></td></tr> |
| 101 | <tr> |
| 102 | <td><a id='tok-defparameter' xml:id='tok-defparameter'>defparameter</a></td> |
| 103 | <td>::=</td> |
| 104 | <td><a class='grammartoken' href="function.html#tok-parameter">parameter</a> ["=" <a class='grammartoken' href="Booleans.html#tok-expression">expression</a>]</td></tr> |
| 105 | <tr> |
| 106 | <td><a id='tok-sublist' xml:id='tok-sublist'>sublist</a></td> |
| 107 | <td>::=</td> |
| 108 | <td><a class='grammartoken' href="function.html#tok-parameter">parameter</a> ("," <a class='grammartoken' href="function.html#tok-parameter">parameter</a>)* [","]</td></tr> |
| 109 | <tr> |
| 110 | <td><a id='tok-parameter' xml:id='tok-parameter'>parameter</a></td> |
| 111 | <td>::=</td> |
| 112 | <td><a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a> | "(" <a class='grammartoken' href="function.html#tok-sublist">sublist</a> ")"</td></tr> |
| 113 | <tr> |
| 114 | <td><a id='tok-funcname' xml:id='tok-funcname'>funcname</a></td> |
| 115 | <td>::=</td> |
| 116 | <td><a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a></td></tr> |
| 117 | </table> |
| 118 | </div> |
| 119 | <a class="grammar-footer" |
| 120 | href="grammar.txt" type="text/plain" |
| 121 | >Download entire grammar as text.</a> |
| 122 | </dd></dl> |
| 123 | |
| 124 | <P> |
| 125 | A function definition is an executable statement. Its execution binds |
| 126 | the function name in the current local namespace to a function object |
| 127 | (a wrapper around the executable code for the function). This |
| 128 | function object contains a reference to the current global namespace |
| 129 | as the global namespace to be used when the function is called. |
| 130 | <a id='l2h-610' xml:id='l2h-610'></a><a id='l2h-611' xml:id='l2h-611'></a> |
| 131 | <P> |
| 132 | The function definition does not execute the function body; this gets |
| 133 | executed only when the function is called. |
| 134 | |
| 135 | <P> |
| 136 | A function definition may be wrapped by one or more decorator expressions. |
| 137 | Decorator expressions are evaluated when the function is defined, in the scope |
| 138 | that contains the function definition. The result must be a callable, |
| 139 | which is invoked with the function object as the only argument. |
| 140 | The returned value is bound to the function name instead of the function |
| 141 | object. Multiple decorators are applied in nested fashion. |
| 142 | For example, the following code: |
| 143 | |
| 144 | <P> |
| 145 | <div class="verbatim"><pre> |
| 146 | @f1(arg) |
| 147 | @f2 |
| 148 | def func(): pass |
| 149 | </pre></div> |
| 150 | |
| 151 | <P> |
| 152 | is equivalent to: |
| 153 | |
| 154 | <P> |
| 155 | <div class="verbatim"><pre> |
| 156 | def func(): pass |
| 157 | func = f1(arg)(f2(func)) |
| 158 | </pre></div> |
| 159 | |
| 160 | <P> |
| 161 | When one or more top-level parameters have the form <var>parameter</var> |
| 162 | <code>=</code> <var>expression</var>, the function is said to have ``default |
| 163 | parameter values.'' For a parameter with a |
| 164 | default value, the corresponding argument may be omitted from a call, |
| 165 | in which case the parameter's default value is substituted. If a |
| 166 | parameter has a default value, all following parameters must also have |
| 167 | a default value -- this is a syntactic restriction that is not |
| 168 | expressed by the grammar. |
| 169 | <a id='l2h-612' xml:id='l2h-612'></a> |
| 170 | <P> |
| 171 | <strong>Default parameter values are evaluated when the function |
| 172 | definition is executed.</strong> This means that the expression is evaluated |
| 173 | once, when the function is defined, and that that same |
| 174 | ``pre-computed'' value is used for each call. This is especially |
| 175 | important to understand when a default parameter is a mutable object, |
| 176 | such as a list or a dictionary: if the function modifies the object |
| 177 | (e.g. by appending an item to a list), the default value is in effect |
| 178 | modified. This is generally not what was intended. A way around this |
| 179 | is to use <code>None</code> as the default, and explicitly test for it in |
| 180 | the body of the function, e.g.: |
| 181 | |
| 182 | <P> |
| 183 | <div class="verbatim"><pre> |
| 184 | def whats_on_the_telly(penguin=None): |
| 185 | if penguin is None: |
| 186 | penguin = [] |
| 187 | penguin.append("property of the zoo") |
| 188 | return penguin |
| 189 | </pre></div> |
| 190 | |
| 191 | <P> |
| 192 | Function call semantics are described in more detail in |
| 193 | section <A href="calls.html#calls">5.3.4</A>. |
| 194 | A function call always assigns values to all parameters mentioned in |
| 195 | the parameter list, either from position arguments, from keyword |
| 196 | arguments, or from default values. If the form ``<code>*identifier</code>'' |
| 197 | is present, it is initialized to a tuple receiving any excess |
| 198 | positional parameters, defaulting to the empty tuple. If the form |
| 199 | ``<code>**identifier</code>'' is present, it is initialized to a new |
| 200 | dictionary receiving any excess keyword arguments, defaulting to a |
| 201 | new empty dictionary. |
| 202 | |
| 203 | <P> |
| 204 | It is also possible to create anonymous functions (functions not bound |
| 205 | to a name), for immediate use in expressions. This uses lambda forms, |
| 206 | described in section <A href="lambdas.html#lambda">5.11</A>. Note that the lambda form is |
| 207 | merely a shorthand for a simplified function definition; a function |
| 208 | defined in a ``<tt class="keyword">def</tt>'' statement can be passed around or |
| 209 | assigned to another name just like a function defined by a lambda |
| 210 | form. The ``<tt class="keyword">def</tt>'' form is actually more powerful since it |
| 211 | allows the execution of multiple statements. |
| 212 | <a id='l2h-613' xml:id='l2h-613'></a> |
| 213 | <P> |
| 214 | <strong>Programmer's note:</strong> Functions are first-class objects. A |
| 215 | ``<code>def</code>'' form executed inside a function definition defines a |
| 216 | local function that can be returned or passed around. Free variables |
| 217 | used in the nested function can access the local variables of the |
| 218 | function containing the def. See section <A href="naming.html#naming">4.1</A> for details. |
| 219 | |
| 220 | <P> |
| 221 | |
| 222 | <DIV CLASS="navigation"> |
| 223 | <div class='online-navigation'> |
| 224 | <p></p><hr /> |
| 225 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 226 | <tr> |
| 227 | <td class='online-navigation'><a rel="prev" title="7.4 The try statement" |
| 228 | href="try.html"><img src='../icons/previous.png' |
| 229 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 230 | <td class='online-navigation'><a rel="parent" title="7. Compound statements" |
| 231 | href="compound.html"><img src='../icons/up.png' |
| 232 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 233 | <td class='online-navigation'><a rel="next" title="7.6 Class definitions" |
| 234 | href="class.html"><img src='../icons/next.png' |
| 235 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 236 | <td align="center" width="100%">Python Reference Manual</td> |
| 237 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 238 | href="contents.html"><img src='../icons/contents.png' |
| 239 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 240 | <td class='online-navigation'><img src='../icons/blank.png' |
| 241 | border='0' height='32' alt='' width='32' /></td> |
| 242 | <td class='online-navigation'><a rel="index" title="Index" |
| 243 | href="genindex.html"><img src='../icons/index.png' |
| 244 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 245 | </tr></table> |
| 246 | <div class='online-navigation'> |
| 247 | <b class="navlabel">Previous:</b> |
| 248 | <a class="sectref" rel="prev" href="try.html">7.4 The try statement</A> |
| 249 | <b class="navlabel">Up:</b> |
| 250 | <a class="sectref" rel="parent" href="compound.html">7. Compound statements</A> |
| 251 | <b class="navlabel">Next:</b> |
| 252 | <a class="sectref" rel="next" href="class.html">7.6 Class definitions</A> |
| 253 | </div> |
| 254 | </div> |
| 255 | <hr /> |
| 256 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 257 | </DIV> |
| 258 | <!--End of Navigation Panel--> |
| 259 | <ADDRESS> |
| 260 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 261 | </ADDRESS> |
| 262 | </BODY> |
| 263 | </HTML> |