Initial commit of OpenSPARC T2 architecture model.
[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / ref / function.html
CommitLineData
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>
577.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>
61A function definition defines a user-defined function object (see
62section&nbsp;<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>(&nbsp;&nbsp;"*" <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>&nbsp;| "**" <a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a></code></td></tr>
97 <tr>
98 <td></td>
99 <td></td>
100 <td><code>&nbsp;| <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>
125A function definition is an executable statement. Its execution binds
126the function name in the current local namespace to a function object
127(a wrapper around the executable code for the function). This
128function object contains a reference to the current global namespace
129as 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>
132The function definition does not execute the function body; this gets
133executed only when the function is called.
134
135<P>
136A function definition may be wrapped by one or more decorator expressions.
137Decorator expressions are evaluated when the function is defined, in the scope
138that contains the function definition. The result must be a callable,
139which is invoked with the function object as the only argument.
140The returned value is bound to the function name instead of the function
141object. Multiple decorators are applied in nested fashion.
142For example, the following code:
143
144<P>
145<div class="verbatim"><pre>
146@f1(arg)
147@f2
148def func(): pass
149</pre></div>
150
151<P>
152is equivalent to:
153
154<P>
155<div class="verbatim"><pre>
156def func(): pass
157func = f1(arg)(f2(func))
158</pre></div>
159
160<P>
161When 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
163parameter values.'' For a parameter with a
164default value, the corresponding argument may be omitted from a call,
165in which case the parameter's default value is substituted. If a
166parameter has a default value, all following parameters must also have
167a default value -- this is a syntactic restriction that is not
168expressed 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
172definition is executed.</strong> This means that the expression is evaluated
173once, when the function is defined, and that that same
174``pre-computed'' value is used for each call. This is especially
175important to understand when a default parameter is a mutable object,
176such 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
178modified. This is generally not what was intended. A way around this
179is to use <code>None</code> as the default, and explicitly test for it in
180the body of the function, e.g.:
181
182<P>
183<div class="verbatim"><pre>
184def 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>
192Function call semantics are described in more detail in
193section&nbsp;<A href="calls.html#calls">5.3.4</A>.
194A function call always assigns values to all parameters mentioned in
195the parameter list, either from position arguments, from keyword
196arguments, or from default values. If the form ``<code>*identifier</code>''
197is present, it is initialized to a tuple receiving any excess
198positional parameters, defaulting to the empty tuple. If the form
199``<code>**identifier</code>'' is present, it is initialized to a new
200dictionary receiving any excess keyword arguments, defaulting to a
201new empty dictionary.
202
203<P>
204It is also possible to create anonymous functions (functions not bound
205to a name), for immediate use in expressions. This uses lambda forms,
206described in section&nbsp;<A href="lambdas.html#lambda">5.11</A>. Note that the lambda form is
207merely a shorthand for a simplified function definition; a function
208defined in a ``<tt class="keyword">def</tt>'' statement can be passed around or
209assigned to another name just like a function defined by a lambda
210form. The ``<tt class="keyword">def</tt>'' form is actually more powerful since it
211allows 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
216local function that can be returned or passed around. Free variables
217used in the nested function can access the local variables of the
218function containing the def. See section&nbsp;<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>
260See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
261</ADDRESS>
262</BODY>
263</HTML>