4.6.1 FieldStorage class

##
4.6.1 FieldStorage class

Access to form data is provided via the `FieldStorage` class. This class is similar to the standard library module `cgi` `FieldStorage`.

class `FieldStorage`( | req[, keep_blank_values, strict_parsing, file_callback, field_callback])

  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.

  The optional argument file_callback allows the application to override both file creation/deletion semantics and location. See 4.6.2 ``FieldStorage Examples'' for additional information. New in version 3.2

  The optional argument field_callback allows the application to override both the creation/deletion semantics and behaviour. New in version 3.2

  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`. A suggested strategy for dealing with this is that any handler should first check for the existance of a `form` attribute within the request object. If this exists, it should be taken to be an existing instance of the `FieldStorage` class and that should be used. If the attribute does not exist and needs to be created, it should be cached as the `form` attribute of the request object so later handler code can use it.

  When the `FieldStorage` class instance is created, 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 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:

  - 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 instance 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:

  `add_field`( | name, value)

    Adds an additional form field with name and value. If a form field already exists with name, the value 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.

    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 `del` operator.

  `clear`( | )

    Removes all form fields. Individual form fields can be deleted using the `del` operator.

  `get`( | name, default)

    If there is only one value associated with form field name, 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 default. A subscript operator is also available which yields the same result except that an exception will be raised where the form field name does not exist.

  `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.

  `has_key`( | name)

    Returns `True` if name is a valid form field. The `in` operator is also supported and will call this method.

  `items`( | )

    Returns a list consisting of tuples for each combination of form field name and value.

  `keys`( | )

    This method returns the names of the form fields. The `len` operator is also supported and will return the number of names which would be returned by this method.