[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / lib / node471.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="node472.html" />
<link rel="prev" href="cgi-intro.html" />
<link rel="parent" href="module-cgi.html" />
<link rel="next" href="node472.html" />
<meta name='aesop' content='information' />
<title>11.2.2 Using the cgi module</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="11.2.1 Introduction"
  href="cgi-intro.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="11.2 cgi  "
  href="module-cgi.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="11.2.3 Higher Level Interface"
  href="node472.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="cgi-intro.html">11.2.1 Introduction</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-cgi.html">11.2 cgi  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node472.html">11.2.3 Higher Level Interface</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION0013220000000000000000">
11.2.2 Using the cgi module</A>
</H2>
<A NAME="Using_the_cgi_module"></A>
<P>
Begin by writing "<tt class="samp">import cgi</tt>".  Do not use "<tt class="samp">from cgi import
*</tt>" -- the module defines all sorts of names for its own use or for
backward compatibility that you don't want in your namespace.

<P>
When you write a new script, consider adding the line:

<P>
<div class="verbatim"><pre>
import cgitb; cgitb.enable()
</pre></div>

<P>
This activates a special exception handler that will display detailed
reports in the Web browser if any errors occur.  If you'd rather not
show the guts of your program to users of your script, you can have
the reports saved to files instead, with a line like this:

<P>
<div class="verbatim"><pre>
import cgitb; cgitb.enable(display=0, logdir="/tmp")
</pre></div>

<P>
It's very helpful to use this feature during script development.
The reports produced by <tt class="module"><a href="module-cgitb.html">cgitb</a></tt> provide information that
can save you a lot of time in tracking down bugs.  You can always
remove the <code>cgitb</code> line later when you have tested your script
and are confident that it works correctly.

<P>
To get at submitted form data,
it's best to use the <tt class="class">FieldStorage</tt> class.  The other classes
defined in this module are provided mostly for backward compatibility.
Instantiate it exactly once, without arguments.  This reads the form
contents from standard input or the environment (depending on the
value of various environment variables set according to the CGI
standard).  Since it may consume standard input, it should be
instantiated only once.

<P>
The <tt class="class">FieldStorage</tt> instance can be indexed like a Python
dictionary, and also supports the standard dictionary methods
<tt class="method">has_key()</tt> and <tt class="method">keys()</tt>.  The built-in <tt class="function">len()</tt>
is also supported.  Form fields containing empty strings are ignored
and do not appear in the dictionary; to keep such values, provide
a true value for the optional <var>keep_blank_values</var> keyword
parameter when creating the <tt class="class">FieldStorage</tt> instance.

<P>
For instance, the following code (which assumes that the 
<span class="mailheader">Content-Type:</span> header and blank line have already been
printed) checks that the fields <code>name</code> and <code>addr</code> are both
set to a non-empty string:

<P>
<div class="verbatim"><pre>
form = cgi.FieldStorage()
if not (form.has_key("name") and form.has_key("addr")):
    print "&lt;H1&gt;Error&lt;/H1&gt;"
    print "Please fill in the name and addr fields."
    return
print "&lt;p&gt;name:", form["name"].value
print "&lt;p&gt;addr:", form["addr"].value
...further form processing here...
</pre></div>

<P>
Here the fields, accessed through "<tt class="samp">form[<var>key</var>]</tt>", are
themselves instances of <tt class="class">FieldStorage</tt> (or
<tt class="class">MiniFieldStorage</tt>, depending on the form encoding).
The <tt class="member">value</tt> attribute of the instance yields the string value
of the field.  The <tt class="method">getvalue()</tt> method returns this string value
directly; it also accepts an optional second argument as a default to
return if the requested key is not present.

<P>
If the submitted form data contains more than one field with the same
name, the object retrieved by "<tt class="samp">form[<var>key</var>]</tt>" is not a
<tt class="class">FieldStorage</tt> or <tt class="class">MiniFieldStorage</tt>
instance but a list of such instances.  Similarly, in this situation,
"<tt class="samp">form.getvalue(<var>key</var>)</tt>" would return a list of strings.
If you expect this possibility
(when your HTML form contains multiple fields with the same name), use
the <tt class="function">getlist()</tt> function, which always returns a list of values (so that you
do not need to special-case the single item case).  For example, this
code concatenates any number of username fields, separated by
commas:

<P>
<div class="verbatim"><pre>
value = form.getlist("username")
usernames = ",".join(value)
</pre></div>

<P>
If a field represents an uploaded file, accessing the value via the
<tt class="member">value</tt> attribute or the <tt class="function">getvalue()</tt> method reads the
entire file in memory as a string.  This may not be what you want.
You can test for an uploaded file by testing either the <tt class="member">filename</tt>
attribute or the <tt class="member">file</tt> attribute.  You can then read the data at
leisure from the <tt class="member">file</tt> attribute:

<P>
<div class="verbatim"><pre>
fileitem = form["userfile"]
if fileitem.file:
    # It's an uploaded file; count lines
    linecount = 0
    while 1:
        line = fileitem.file.readline()
        if not line: break
        linecount = linecount + 1
</pre></div>

<P>
The file upload draft standard entertains the possibility of uploading
multiple files from one field (using a recursive
<span class="mimetype">multipart/*</span> encoding).  When this occurs, the item will be
a dictionary-like <tt class="class">FieldStorage</tt> item.  This can be determined
by testing its <tt class="member">type</tt> attribute, which should be
<span class="mimetype">multipart/form-data</span> (or perhaps another MIME type matching
<span class="mimetype">multipart/*</span>).  In this case, it can be iterated over
recursively just like the top-level form object.

<P>
When a form is submitted in the ``old'' format (as the query string or
as a single data part of type
<span class="mimetype">application/x-www-form-urlencoded</span>), the items will actually
be instances of the class <tt class="class">MiniFieldStorage</tt>.  In this case, the
<tt class="member">list</tt>, <tt class="member">file</tt>, and <tt class="member">filename</tt> attributes are
always <code>None</code>.

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="11.2.1 Introduction"
  href="cgi-intro.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="11.2 cgi  "
  href="module-cgi.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="11.2.3 Higher Level Interface"
  href="node472.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="cgi-intro.html">11.2.1 Introduction</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-cgi.html">11.2 cgi  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node472.html">11.2.3 Higher Level Interface</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
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="lib.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="lib.html" title='Python Library Reference' />
	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="node472.html" />
	13	<link rel="prev" href="cgi-intro.html" />
	14	<link rel="parent" href="module-cgi.html" />
	15	<link rel="next" href="node472.html" />
	16	<meta name='aesop' content='information' />
	17	<title>11.2.2 Using the cgi module</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="11.2.1 Introduction"
	25	href="cgi-intro.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="11.2 cgi "
	28	href="module-cgi.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="11.2.3 Higher Level Interface"
	31	href="node472.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 Library Reference</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'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	38	border='0' height='32' alt='Module Index' width='32' /></a></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="cgi-intro.html">11.2.1 Introduction</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="module-cgi.html">11.2 cgi </A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="node472.html">11.2.3 Higher Level Interface</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H2><A NAME="SECTION0013220000000000000000">
	56	11.2.2 Using the cgi module</A>
	57	</H2>
	58	<A NAME="Using_the_cgi_module"></A>
	59	<P>
	60	Begin by writing "<tt class="samp">import cgi</tt>". Do not use "<tt class="samp">from cgi import
	61	*</tt>" -- the module defines all sorts of names for its own use or for
	62	backward compatibility that you don't want in your namespace.
	63
	64	<P>
65	When you write a new script, consider adding the line:
66
67	<P>
68	<div class="verbatim"><pre>
69	import cgitb; cgitb.enable()
70	</pre></div>
71
72	<P>
73	This activates a special exception handler that will display detailed
74	reports in the Web browser if any errors occur. If you'd rather not
75	show the guts of your program to users of your script, you can have
76	the reports saved to files instead, with a line like this:
77
78	<P>
79	<div class="verbatim"><pre>
80	import cgitb; cgitb.enable(display=0, logdir="/tmp")
81	</pre></div>
82
83	<P>
84	It's very helpful to use this feature during script development.
85	The reports produced by <tt class="module"><a href="module-cgitb.html">cgitb</a></tt> provide information that
86	can save you a lot of time in tracking down bugs. You can always
87	remove the <code>cgitb</code> line later when you have tested your script
88	and are confident that it works correctly.
89
90	<P>
91	To get at submitted form data,
92	it's best to use the <tt class="class">FieldStorage</tt> class. The other classes
93	defined in this module are provided mostly for backward compatibility.
94	Instantiate it exactly once, without arguments. This reads the form
95	contents from standard input or the environment (depending on the
96	value of various environment variables set according to the CGI
97	standard). Since it may consume standard input, it should be
98	instantiated only once.
99
100	<P>
101	The <tt class="class">FieldStorage</tt> instance can be indexed like a Python
102	dictionary, and also supports the standard dictionary methods
103	<tt class="method">has_key()</tt> and <tt class="method">keys()</tt>. The built-in <tt class="function">len()</tt>
104	is also supported. Form fields containing empty strings are ignored
105	and do not appear in the dictionary; to keep such values, provide
106	a true value for the optional <var>keep_blank_values</var> keyword
107	parameter when creating the <tt class="class">FieldStorage</tt> instance.
108
109	<P>
110	For instance, the following code (which assumes that the
111	<span class="mailheader">Content-Type:</span> header and blank line have already been
112	printed) checks that the fields <code>name</code> and <code>addr</code> are both
113	set to a non-empty string:
114
115	<P>
116	<div class="verbatim"><pre>
117	form = cgi.FieldStorage()
118	if not (form.has_key("name") and form.has_key("addr")):
119	print "<H1>Error</H1>"
120	print "Please fill in the name and addr fields."
121	return
122	print "<p>name:", form["name"].value
123	print "<p>addr:", form["addr"].value
124	...further form processing here...
125	</pre></div>
126
127	<P>
128	Here the fields, accessed through "<tt class="samp">form[<var>key</var>]</tt>", are
129	themselves instances of <tt class="class">FieldStorage</tt> (or
130	<tt class="class">MiniFieldStorage</tt>, depending on the form encoding).
131	The <tt class="member">value</tt> attribute of the instance yields the string value
132	of the field. The <tt class="method">getvalue()</tt> method returns this string value
133	directly; it also accepts an optional second argument as a default to
134	return if the requested key is not present.
135
136	<P>
137	If the submitted form data contains more than one field with the same
138	name, the object retrieved by "<tt class="samp">form[<var>key</var>]</tt>" is not a
139	<tt class="class">FieldStorage</tt> or <tt class="class">MiniFieldStorage</tt>
140	instance but a list of such instances. Similarly, in this situation,
141	"<tt class="samp">form.getvalue(<var>key</var>)</tt>" would return a list of strings.
142	If you expect this possibility
143	(when your HTML form contains multiple fields with the same name), use
144	the <tt class="function">getlist()</tt> function, which always returns a list of values (so that you
145	do not need to special-case the single item case). For example, this
146	code concatenates any number of username fields, separated by
147	commas:
148
149	<P>
150	<div class="verbatim"><pre>
151	value = form.getlist("username")
152	usernames = ",".join(value)
153	</pre></div>
154
155	<P>
156	If a field represents an uploaded file, accessing the value via the
157	<tt class="member">value</tt> attribute or the <tt class="function">getvalue()</tt> method reads the
158	entire file in memory as a string. This may not be what you want.
159	You can test for an uploaded file by testing either the <tt class="member">filename</tt>
160	attribute or the <tt class="member">file</tt> attribute. You can then read the data at
161	leisure from the <tt class="member">file</tt> attribute:
162
163	<P>
164	<div class="verbatim"><pre>
165	fileitem = form["userfile"]
166	if fileitem.file:
167	# It's an uploaded file; count lines
168	linecount = 0
169	while 1:
170	line = fileitem.file.readline()
171	if not line: break
172	linecount = linecount + 1
173	</pre></div>
174
175	<P>
176	The file upload draft standard entertains the possibility of uploading
177	multiple files from one field (using a recursive
178	<span class="mimetype">multipart/*</span> encoding). When this occurs, the item will be
179	a dictionary-like <tt class="class">FieldStorage</tt> item. This can be determined
180	by testing its <tt class="member">type</tt> attribute, which should be
181	<span class="mimetype">multipart/form-data</span> (or perhaps another MIME type matching
182	<span class="mimetype">multipart/*</span>). In this case, it can be iterated over
183	recursively just like the top-level form object.
184
185	<P>
186	When a form is submitted in the ``old'' format (as the query string or
187	as a single data part of type
188	<span class="mimetype">application/x-www-form-urlencoded</span>), the items will actually
189	be instances of the class <tt class="class">MiniFieldStorage</tt>. In this case, the
190	<tt class="member">list</tt>, <tt class="member">file</tt>, and <tt class="member">filename</tt> attributes are
191	always <code>None</code>.
192
193	<P>
194
195	<DIV CLASS="navigation">
196	<div class='online-navigation'>
197	<p></p><hr />
198	<table align="center" width="100%" cellpadding="0" cellspacing="2">
199	<tr>
200	<td class='online-navigation'><a rel="prev" title="11.2.1 Introduction"
201	href="cgi-intro.html"><img src='../icons/previous.png'
202	border='0' height='32' alt='Previous Page' width='32' /></A></td>
203	<td class='online-navigation'><a rel="parent" title="11.2 cgi "
204	href="module-cgi.html"><img src='../icons/up.png'
205	border='0' height='32' alt='Up One Level' width='32' /></A></td>
206	<td class='online-navigation'><a rel="next" title="11.2.3 Higher Level Interface"
207	href="node472.html"><img src='../icons/next.png'
208	border='0' height='32' alt='Next Page' width='32' /></A></td>
209	<td align="center" width="100%">Python Library Reference</td>
210	<td class='online-navigation'><a rel="contents" title="Table of Contents"
211	href="contents.html"><img src='../icons/contents.png'
212	border='0' height='32' alt='Contents' width='32' /></A></td>
213	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
214	border='0' height='32' alt='Module Index' width='32' /></a></td>
215	<td class='online-navigation'><a rel="index" title="Index"
216	href="genindex.html"><img src='../icons/index.png'
217	border='0' height='32' alt='Index' width='32' /></A></td>
218	</tr></table>
219	<div class='online-navigation'>
220	<b class="navlabel">Previous:</b>
221	<a class="sectref" rel="prev" href="cgi-intro.html">11.2.1 Introduction</A>
222	<b class="navlabel">Up:</b>
223	<a class="sectref" rel="parent" href="module-cgi.html">11.2 cgi </A>
224	<b class="navlabel">Next:</b>
225	<a class="sectref" rel="next" href="node472.html">11.2.3 Higher Level Interface</A>
226	</div>
227	</div>
228	<hr />
229	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
230	</DIV>
231	<!--End of Navigation Panel-->
232	<ADDRESS>
233	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
234	</ADDRESS>
235	</BODY>
236	</HTML>