zope.httpform 1.0.0

This package provides a WSGI-oriented HTTP form parser with interesting features to make form handling easier. This functionality has lived for a long time inside Zope’s publisher, but has been broken out into a separate package to make it easier to test, explain, understand, and use.

The FormParser class uses Python’s standard cgi.FieldStorage class, but is easier to use than FieldStorage. The parser converts field names and values to Unicode, handles file uploads in a graceful manner, and allows field name suffixes that tell the parser how to handle each field. The available suffixes are:

• :int – convert to an integer

• :float – convert to a float

• :long – convert to a long integer

• :string – convert to a string instead of Unicode

• :required – raise ValueError if the field is not provided

• :tokens – split the input on whitespace characters

• :lines – split multiline input into a list of lines

• :text – convert multiline text to a string instead of Unicode

• :boolean – true if nonempty, false if empty

• :list – make a list even if there is only one value

• :tuple – make a tuple

• :action – specify the form action

• :method – same as :action

• :default – provide a default value

• :record – generate a record object

• :records – generate a list of record object

• :ignore_empty – discard the field value if it’s empty

• :default_action – specifies a default form action

• :default_method – same as :default_action

Here are some examples of ways to use these suffixes.

• Using this package, you can provide a default for a field in an HTML form:

  <input type="text" name="country:ignore_empty" />
  <input type="hidden" name="country:default" value="Chile" />

  The FormData class in this package will convert that form submission to a mapping containing a Unicode value for the country field. If the user leaves the field empty, the country field will have the value of "Chile".

• You can ensure that certain variables are placed in a list, even when only one value is selected:

  <select name="cars:list" multiple="multiple">
  <option value="volvo">Volvo</option>
  <option value="saab">Saab</option>
  <option value="mercedes">Mercedes</option>
  <option value="audi">Audi</option>
  </select>

• You can group data into record objects, which is very useful for complex forms:

  <input type="text" name="shipping.name:record" />
  <input type="text" name="shipping.address:record" />
  <input type="text" name="shipping.phone:record" />
  <input type="text" name="billing.name:record" />
  <input type="text" name="billing.address:record" />
  <input type="text" name="billing.phone:record" />

You can do a lot more with these suffixes. See src/zope/httpform/README.txt for a demonstration and test of all features.