<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="modpython.css" type='text/css' />
<link rel="first" href="modpython.html" title='Mod_python Manual' />
<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="pyapi-util-fstor-examples.html" />
<link rel="prev" href="pyapi-util.html" />
<link rel="parent" href="pyapi-util.html" />
<link rel="next" href="pyapi-util-fstor-examples.html" />
<meta name='aesop' content='information' />
<title>4.6.1 FieldStorage class</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="4.6 util - Miscellaneous"
href="pyapi-util.html"><img src='previous.png'
border='0' height='32' alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4.6 util - Miscellaneous"
href="pyapi-util.html"><img src='up.png'
border='0' height='32' alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.6.2 FieldStorage Examples"
href="pyapi-util-fstor-examples.html"><img src='next.png'
border='0' height='32' alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Mod_python Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
href="contents.html"><img src='contents.png'
border='0' height='32' alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='blank.png'
border='0' height='32' alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
href="genindex.html"><img src='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="pyapi-util.html">4.6 util - Miscellaneous</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="pyapi-util.html">4.6 util - Miscellaneous</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="pyapi-util-fstor-examples.html">4.6.2 FieldStorage Examples</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->
<H2><A NAME="SECTION006610000000000000000"></A><A NAME="pyapi-util-fstor"></A>
<BR>
4.6.1 FieldStorage class
</H2>
<P>
Access to form data is provided via the <tt class="class">FieldStorage</tt>
class. This class is similar to the standard library module
<tt class="module">cgi</tt> <tt class="class">FieldStorage</tt>.
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-206' xml:id='l2h-206' class="class">FieldStorage</tt></b>(</nobr></td>
<td><var>req</var><big>[</big><var>, keep_blank_values, strict_parsing, file_callback, field_callback</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
This class provides uniform access to HTML form data submitted by the
client. <var>req</var> is an instance of the mod_python request object.
<P>
The optional argument <var>keep_blank_values</var> is a flag indicating
whether blank values in URL encoded form data should be treated as
blank strings. The default is false, which means that blank values are
ignored as if they were not included.
<P>
The optional argument <var>strict_parsing</var> is not yet implemented.
<P>
The optional argument <var>file_callback</var> allows the application to override
both file creation/deletion semantics and location. See
<A href="pyapi-util-fstor-examples.html#pyapi-util-fstor-examples">4.6.2</A> ``FieldStorage Examples'' for additional
information. <em>New in version 3.2</em>
<P>
The optional argument <var>field_callback</var> allows the application to override
both the creation/deletion semantics and behaviour. <em>New in version 3.2</em>
<P>
During initialization, <tt class="class">FieldStorage</tt> class reads all of the
data provided by the client. Since all data provided by the client is
consumed at this point, there should be no more than one
<tt class="class">FieldStorage</tt> class instantiated per single request, nor should
you make any attempts to read client data before or after
instantiating a <tt class="class">FieldStorage</tt>. A suggested strategy for dealing
with this is that any handler should first check for the existance of
a <code>form</code> attribute within the request object. If this exists, it
should be taken to be an existing instance of the <tt class="class">FieldStorage</tt>
class and that should be used. If the attribute does not exist
and needs to be created, it should be cached as the <code>form</code>
attribute of the request object so later handler code can use it.
<P>
When the <tt class="class">FieldStorage</tt> class instance is created, the data read
from the client is then parsed into separate fields and packaged in
<tt class="class">Field</tt> objects, one per field. For HTML form inputs of type
<code>file</code>, a temporary file is created that can later be accessed via
the <tt class="member">file</tt> attribute of a <tt class="class">Field</tt> object.
<P>
The <tt class="class">FieldStorage</tt> class has a mapping object interface, i.e. it
can be treated like a dictionary in most instances, but is not strictly
compatible as is it missing some methods provided by dictionaries and
some methods don't behave entirely like their counterparts, especially
when there is more than one value associated with a form field. When used
as a mapping, the keys are form input names, and the returned dictionary
value can be:
<P>
<UL>
<LI>An instance of <tt class="class">StringField</tt>, containing the form input
value. This is only when there is a single value corresponding to the
input name. <tt class="class">StringField</tt> is a subclass of <tt class="class">str</tt> which
provides the additional <tt class="member">value</tt> attribute for compatibility
with standard library <tt class="module">cgi</tt> module.
</LI>
<LI>An instance of a <tt class="class">Field</tt> class, if the input is a file upload.
</LI>
<LI>A list of <tt class="class">StringField</tt> and/or <tt class="class">Field</tt> objects. This is
when multiple values exist, such as for a <code><select></code> HTML form
element.
</LI>
</UL>
<P>
<div class="note"><b class="label">Note:</b>
Unlike the standard library <tt class="module">cgi</tt> module
<tt class="class">FieldStorage</tt> class, a <tt class="class">Field</tt> object is returned
<em>only</em> when it is a file upload. In all other cases the
return is an instance of <tt class="class">StringField</tt>. This means that you
do not need to use the <tt class="member">.value</tt> attribute to access values
of fields in most cases.
</div>
<P>
In addition to standard mapping object methods, <tt class="class">FieldStorage</tt> objects
have the following attributes:
<P>
<dl><dt><b><tt id='l2h-207' xml:id='l2h-207' class="member">list</tt></b></dt>
<dd>
This is a list of <tt class="class">Field</tt> objects, one for each input. Multiple
inputs with the same name will have multiple elements in this list.
</dl>
<P>
<tt class="class">FieldStorage</tt> methods:
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-208' xml:id='l2h-208' class="method">add_field</tt></b>(</nobr></td>
<td><var>name, value</var>)</td></tr></table></dt>
<dd>
Adds an additional form field with <var>name</var> and <var>value</var>.
If a form field already exists with <var>name</var>, the <var>value</var>
will be added to the list of existing values for the form field.
This method should be used for adding additional fields in
preference to adding new fields direct to the list of fields.
<P>
If the value associated with a field should be replaced when it
already exists, rather than an additional value being associated
with the field, the dictionary like subscript operator should
be used to set the value, or the existing field deleted altogether
first using the <code>del</code> operator.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-209' xml:id='l2h-209' class="method">clear</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
Removes all form fields. Individual form fields can be deleted
using the <code>del</code> operator.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-210' xml:id='l2h-210' class="method">get</tt></b>(</nobr></td>
<td><var>name, default</var>)</td></tr></table></dt>
<dd>
If there is only one value associated with form field <var>name</var>, that
single value will be returned. If there are multiple values, a list is
returned holding all values. If no such form field or value exists then
the method returns the value specified by the parameter <var>default</var>.
A subscript operator is also available which yields the same result
except that an exception will be raised where the form field <var>name</var>
does not exist.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-211' xml:id='l2h-211' class="method">getfirst</tt></b>(</nobr></td>
<td><var>name</var><big>[</big><var>, default</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Always returns only one value associated with form field
<var>name</var>. If no such form field or value exists then the method
returns the value specified by the optional parameter
<var>default</var>. This parameter defaults to <code>None</code> if not
specified.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-212' xml:id='l2h-212' class="method">getlist</tt></b>(</nobr></td>
<td><var>name</var>)</td></tr></table></dt>
<dd>
This method always returns a list of values associated with form
field <var>name</var>. The method returns an empty list if no such form
field or value exists for <var>name</var>. It returns a list consisting
of one item if only one such value exists.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-213' xml:id='l2h-213' class="method">has_key</tt></b>(</nobr></td>
<td><var>name</var>)</td></tr></table></dt>
<dd>
Returns <code>True</code> if <var>name</var> is a valid form field. The <code>in</code>
operator is also supported and will call this method.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-214' xml:id='l2h-214' class="method">items</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
Returns a list consisting of tuples for each combination of form
field name and value.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-215' xml:id='l2h-215' class="method">keys</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
This method returns the names of the form fields. The <code>len</code>
operator is also supported and will return the number of names
which would be returned by this method.
</dl>
<P>
</dl>
<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="4.6 util - Miscellaneous"
href="pyapi-util.html"><img src='previous.png'
border='0' height='32' alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4.6 util - Miscellaneous"
href="pyapi-util.html"><img src='up.png'
border='0' height='32' alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.6.2 FieldStorage Examples"
href="pyapi-util-fstor-examples.html"><img src='next.png'
border='0' height='32' alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Mod_python Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
href="contents.html"><img src='contents.png'
border='0' height='32' alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='blank.png'
border='0' height='32' alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
href="genindex.html"><img src='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="pyapi-util.html">4.6 util - Miscellaneous</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="pyapi-util.html">4.6 util - Miscellaneous</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="pyapi-util-fstor-examples.html">4.6.2 FieldStorage Examples</A>
</div>
</div>
<hr />
<span class="release-info">Release 3.3.1, documentation updated on January 29, 2007.</span>
</DIV>
<!--End of Navigation Panel-->
</BODY>
</HTML>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
15533144ea879a3ee7f2cdcbb31e4859
>
files
>
124
