This class provides uniform access to HTML form data submitted by the
client. req is an instance of the mod_python request object.
The optional argument keep_blank_values 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.
The optional argument strict_parsing is not yet implemented.
During initialization, FieldStorage 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
FieldStorage class instantiated per single request, nor should
you make any attempts to read client data before or after
instantiating a FieldStorage.
The data read from the client is then parsed into separate fields and
packaged in Field objects, one per field. For HTML form inputs
of type file, a temporary file is created that can later be
accessed via the file attribute of a Field object.
The FieldStorage class has a mapping object interface, i.e. it
can be treated like a dictionary. When used as a mapping, the keys are
form input names, and the returned dictionary value can be:
- An instance of StringField, containing the form input
value. This is only when there is a single value corresponding to the
input name. StringField is a subclass of str which
provides the additional value attribute for compatibility
with standard library cgi module.
- An instances of a Field class, if the input is a file upload.
- A list of StringField and/or Field objects. This is
when multiple values exist, such as for a
<select> HTML form
element.
Note:
Unlike the standard library cgi module
FieldStorage class, a Field object is returned
only when it is a file upload. In all other cases the
return is an instance of StringField. This means that you
do not need to use the .value attribute to access values
of fields in most cases.
In addition to standard mapping object methods, FieldStorage objects
have the following attributes:
- list
-
This is a list of Field objects, one for each input. Multiple
inputs with the same name will have multiple elements in this list.
FieldStorage methods:
- getfirst(name[, default])
-
Always returns only one value associated with form field
name. If no such form field or value exists then the method
returns the value specified by the optional parameter
default. This parameter defaults to
None if not
specified.
- getlist(name)
-
This method always returns a list of values associated with form
field name. The method returns an empty list if no such form
field or value exists for name. It returns a list consisting
of one item if only one such value exists.
