[Checkins] SVN: zope.httpform/trunk/ More documentation
Shane Hathaway
shane at hathawaymix.org
Fri Feb 6 02:19:42 EST 2009
Log message for revision 96170:
More documentation
Changed:
U zope.httpform/trunk/README.txt
U zope.httpform/trunk/src/zope/httpform/README.txt
U zope.httpform/trunk/src/zope/httpform/__init__.py
U zope.httpform/trunk/src/zope/httpform/interfaces.py
U zope.httpform/trunk/src/zope/httpform/parser.py
-=-
Modified: zope.httpform/trunk/README.txt
===================================================================
--- zope.httpform/trunk/README.txt 2009-02-06 06:43:14 UTC (rev 96169)
+++ zope.httpform/trunk/README.txt 2009-02-06 07:19:41 UTC (rev 96170)
@@ -5,10 +5,10 @@
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 parser 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 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
@@ -38,8 +38,10 @@
<input type="text" name="country:ignore_empty" />
<input type="hidden" name="country:default" value="Chile" />
- The form data returned by the parser will have a Unicode value for the
- ``country`` field, even if the user does not enter anything into the text box.
+ 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::
Modified: zope.httpform/trunk/src/zope/httpform/README.txt
===================================================================
--- zope.httpform/trunk/src/zope/httpform/README.txt 2009-02-06 06:43:14 UTC (rev 96169)
+++ zope.httpform/trunk/src/zope/httpform/README.txt 2009-02-06 07:19:41 UTC (rev 96170)
@@ -2,6 +2,8 @@
Tests of zope.httpform
======================
+.. contents::
+
Basic Usage
-----------
@@ -419,8 +421,8 @@
>>> pprint.pprint(FormParser(env).parse())
{}
-File Upload
------------
+Uploading Files
+---------------
Here is an example of what browsers send when users upload a file using
an HTML form:
@@ -511,3 +513,16 @@
>>> data[:12]
'012345678901'
+For The Curious
+---------------
+
+What happens if you call the parse() method a second time? It re-parses the
+WSGI/CGI environment.
+
+ >>> env = {'REQUEST_METHOD': 'GET', 'QUERY_STRING': 'x:int=1'}
+ >>> p = FormParser(env)
+ >>> p.parse()
+ {u'x': 1}
+ >>> env['QUERY_STRING'] = 'y:int=2'
+ >>> p.parse()
+ {u'y': 2}
Modified: zope.httpform/trunk/src/zope/httpform/__init__.py
===================================================================
--- zope.httpform/trunk/src/zope/httpform/__init__.py 2009-02-06 06:43:14 UTC (rev 96169)
+++ zope.httpform/trunk/src/zope/httpform/__init__.py 2009-02-06 07:19:41 UTC (rev 96170)
@@ -1,4 +1,7 @@
+"""HTTP form parser that supports file uploads, Unicode, and various suffixes.
+"""
+
from zope.httpform.parser import FormParser
__all__ = ('FormParser',)
Modified: zope.httpform/trunk/src/zope/httpform/interfaces.py
===================================================================
--- zope.httpform/trunk/src/zope/httpform/interfaces.py 2009-02-06 06:43:14 UTC (rev 96169)
+++ zope.httpform/trunk/src/zope/httpform/interfaces.py 2009-02-06 07:19:41 UTC (rev 96170)
@@ -28,7 +28,7 @@
"""Parse the form data and return it as a mapping.
Before parsing the form data, this method verifies the
- WSGI environment contains valid form data. If it does not,
+ WSGI/CGI environment contains form data. If it does not,
this method returns an empty mapping.
Returns the mapping of form data.
@@ -64,7 +64,7 @@
"""
headers = Attribute("headers",
- """A dictionary containing the file upload headers""")
+ """An rfc822.Message containing the file upload headers""")
filename = Attribute("filename",
"""The name of the uploaded file, in Unicode""")
Modified: zope.httpform/trunk/src/zope/httpform/parser.py
===================================================================
--- zope.httpform/trunk/src/zope/httpform/parser.py 2009-02-06 06:43:14 UTC (rev 96169)
+++ zope.httpform/trunk/src/zope/httpform/parser.py 2009-02-06 07:19:41 UTC (rev 96170)
@@ -13,8 +13,35 @@
##############################################################################
"""HTTP form parser that supports file uploads, Unicode, and various suffixes.
+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``
+
$Id: $
"""
+__docformat__ = 'restructuredtext'
from cgi import FieldStorage
from cStringIO import StringIO
@@ -40,6 +67,7 @@
class FormParser(object):
+ """Form data parser."""
implements(IFormParser)
def __init__(self, env, wsgi_input=None, to_unicode=None):
@@ -61,11 +89,12 @@
def to_unicode(s):
return s.decode()
self._to_unicode = to_unicode
+
+ def parse(self):
+ """See IFormParser."""
self.form = {}
self.action = None
- def parse(self):
- """See IFormParser."""
method = self._env['REQUEST_METHOD'].upper()
if method in ('GET', 'HEAD'):
# Look for a query string instead of an input body
More information about the Checkins
mailing list