Commit | Line | Data |
---|---|---|
920dae64 AT |
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> |