Package: zope.httpform
zope.httpformis a library that, given a WSGI or CGI environment
dictionary, will return a dictionary back containing converted
form/query string elements.  The form and query string elements
contained in the environment are converted into simple Python types when
the form element names are decorated with special suffixes.  For
example, in an HTML form that you’d like this library to process,
you might say:<form action=".">
   Age : <input type="hidden" name="age:int" value="20"/>
   <input type="submit" name="Submit"/>
</form>Likewise, in the query string of the URL, you could put:http://example.com/mypage?age:int=20In both of these cases, when provided the WSGI or CGI environment,
and asked to return a value, this library will return a dictionary
like so:{'age':20}This functionality has lived for a long time inside Zope’s publisher,
but now it has been factored into this small library, making it easier
to explain, test, and use.ContentsForm/Query String Element ParsingGotchasAcknowledgementsCHANGESVersion 1.0.2 (2009-07-24)Version 1.0.1 (2009-02-07)Version 1.0.0 (2009-02-06)Form/Query String Element Parsingzope.httpformprovides a way for you to specify form input types in
the form, rather than in your application code. Instead of converting
theagevariable to an integer in a controller or view, you can
indicate that it is an integer in the form itself:Age <input type="text" name="age:int" />The:intappended to the form input name tells this library to
convert the form input to an integer when it is invoked.  If the
user of your form types something that cannot be converted to an
integer in the above case (such as “22 going on 23”) then this library
will raise a ValueError.Here is a list of the standard parameter converters.:booleanConverts a variable to true or false.  Empty strings are evaluated as
false and non-empty strings are evaluated as true.:intConverts a variable to an integer.:longConverts a variable to a long integer.:floatConverts a variable to a floating point number.:stringConverts a variable to a string.  Most variables are strings already,
so this converter is not often used except to simplify file uploads.:textConverts a variable to a string with normalized line breaks.
Different browsers on various platforms encode line endings
differently, so this script makes sure the line endings are
consistent, regardless of how they were encoded by the browser.:listConverts a variable to a Python list.:tupleConverts a variable to a Python tuple.:tokensConverts a string to a list by breaking it on white spaces.:linesConverts a string to a list by breaking it on new lines.:requiredRaises an exception if the variable is not present.:ignore_emptyExcludes the variable from the form data if the variable is an empty
string.These converters all work in more or less the same way to coerce a
form variable, which is a string, into another specific type.The:listand:tupleconverters can be used in combination with
other converters.  This allows you to apply additional converters to
each element of the list or tuple.  Consider this form:<form action=".">

  <p>I like the following numbers</p>

  <input type="checkbox" name="favorite_numbers:list:int"
  value="1" /> One<br />

  <input type="checkbox" name="favorite_numbers:list:int"
  value="2" />Two<br />

  <input type="checkbox" name="favorite_numbers:list:int"
  value="3" />Three<br />

  <input type="checkbox" name="favorite_numbers:list:int"
  value="4" />Four<br />

  <input type="checkbox" name="favorite_numbers:list:int"
  value="5" />5<br />

  <input type="submit" />
</form>By using the:listand:intconverters together, this library
will convert each selected item to an integer and then combine all
selected integers into a list namedfavorite_numbers.A more complex type of form conversion is to convert a series of
inputs intorecords. Records are structures that have
attributes. Using records, you can combine a number of form inputs
into one variable with attributes.  The available record converters
are::recordConverts a variable to a record attribute.:recordsConverts a variable to a record attribute in a list of records.:defaultProvides a default value for a record attribute if the variable is
empty.:ignore_emptySkips a record attribute if the variable is empty.Here are some examples of how these converters are used:<form action=".">

  First Name <input type="text" name="person.fname:record" /><br />
  Last Name <input type="text" name="person.lname:record" /><br />
  Age <input type="text" name="person.age:record:int" /><br />

  <input type="submit" />
</form>If the information represented by this form post is passed tozope.httpform, the resulting dictionary will container one parameter,person. Thepersonvariable will have the attributesfname,lnameandage. Here’s an example of how you might usezope.httpformto process the form post (assuming you have a WSGI
or CGI environment in hand):from zope.httpform import parse

info = parse(environ, environ['wsgi.input'])
person = info['person']
full_name = "%s %s" % (person.fname, person.lname)
if person.age < 21:
    return ("Sorry, %s. You are not old enough to adopt an "
            "aardvark." % full_name)
return "Thanks, %s. Your aardvark is on its way." % full_nameTherecordsconverter works like therecordconverter except
that it produces a list of records, rather than just one. Here is
an example form:<form action=".">

  <p>Please, enter information about one or more of your next of
  kin.</p>

  <p>
    First Name <input type="text" name="people.fname:records" />
    Last Name <input type="text" name="people.lname:records" />
  </p>

  <p>
    First Name <input type="text" name="people.fname:records" />
    Last Name <input type="text" name="people.lname:records" />
  </p>

  <p>
    First Name <input type="text" name="people.fname:records" />
    Last Name <input type="text" name="people.lname:records" />
  </p>

  <input type="submit" />
</form>If you callzope.httpform’s parse method with the information
from this form post, a dictionary will be returned from it with a
variable calledpeoplethat is a list of records. Each record will
havefnameandlnameattributes.  Note the difference between therecordsconverter and thelist:recordconverter: the former would
create a list of records, whereas the latter would produce a single
record whose attributesfnameandlnamewould each be a list of
values.The order of combined modifiers does not matter; for example,:int:listis identical to:list:int.GotchasThe file pointer passed tozope.httpform.parse()will be
consumed.  For all intents and purposes this means you should make a
tempfile copy of thewsgi.inputfile pointer before callingparse()if you intend to use the POST file input data in your
application.AcknowledgementsThis documentation was graciously donated by the team at
Agendaless Consulting.  Thezope.httpformpackage is
expected to replace therepoze.montypackage.CHANGESVersion 1.0.2 (2009-07-24)Include package data in release.Default to UTF-8 decodingFixed a test failure on Python 2.6Version 1.0.1 (2009-02-07)Fixed some misleading documentation.Relaxed the requirement for REQUEST_METHOD because the zope.publisher
tests do not set it.Used documentation and design ideas from repoze.monty.  Thanks,
Chris and Agendaless.Version 1.0.0 (2009-02-06)First release of zope.httpform.  Extracted from zope.publisher 3.5.5.