SVN: r24300 - trunk/quixote/form2

Author: nascheme
Date: 2004-05-20 13:42:46 -0400 (Thu, 20 May 2004)
New Revision: 24300

Modified:
   trunk/quixote/form2/form.py
Log:
Provide more documentation for the Form class.  We still need a longer
document explaining forms in the 'doc' directory, IMHO.


Modified: trunk/quixote/form2/form.py
===================================================================
--- trunk/quixote/form2/form.py	2004-05-20 17:04:56 UTC (rev 24299)
+++ trunk/quixote/form2/form.py	2004-05-20 17:42:46 UTC (rev 24300)
@@ -41,12 +41,19 @@
 
 
 class Form:
-    # XXX needs a nice docstring that explains typical usage!
     """
+    Provides a high-level mechanism for collecting and processing user
+    input that is based on HTML forms.
+
     Instance attributes:
       widgets : [Widget]
+        widgets that are not subclasses of SubmitWidget or HiddenWidget
       submit_widgets : [SubmitWidget]
+        subclasses of SubmitWidget, normally rendered at the end of the
+        form
       hidden_widgets : [HiddenWidget]
+        subclasses of HiddenWidget, normally rendered at the beginning
+        of the form
       _names : { name:string : Widget }
         names used in the form and the widgets associated with them
     """
@@ -104,7 +111,8 @@
 
     def __getitem__(self, name):
         """(name:string) -> any
-        Return a widget's value.
+        Return a widget's value.  Raises KeyError if widget named 'name'
+        does not exist.
         """
         try:
             return self._names[name].parse()
@@ -115,7 +123,11 @@
         """Return true if the widget named 'name' is in the form."""
         return self._names.has_key(name)
 
-    def get(self, name):
+    def get(self, name, default=None):
+        """(name:string, default=None) -> any
+        Return a widget's value.  Returns 'default' if widget named 'name'
+        does not exist.
+        """
         widget = self._names.get(name)
         if widget is not None:
             return widget.parse()
@@ -124,13 +136,23 @@
 
     def get_widget(self, name):
         """(name:string) -> Widget | None
+        Return the widget named 'name'.  Returns None if the widget does
+        not exist.
         """
         return self._names.get(name)
 
     def get_submit_widgets(self):
+        """() -> [SubmitWidget]
+        """
         return self.submit_widgets
 
     def get_all_widgets(self):
+        """() -> [Widget]
+        Return all the widgets that have been added to the form.  Note that
+        this while this list includes submit widgets and hidden widgets, it
+        does not include sub-widgets (e.g. widgets that are part of
+        CompositeWidgets)
+        """
         return self._names.values()
 
     # -- Form processing and error checking ----------------------------
@@ -138,7 +160,11 @@
     def is_submitted(self):
         """() -> bool
 
-        Return true if a form was submitted.
+        Return true if a form was submitted.  If the form method is 'POST'
+        and the page was not requested using 'POST', then the form is not
+        considered to be submitted.  If the form method is 'GET' then the
+        form is considered submitted if there is any form data in the
+        request.
         """
         request = get_request()
         if self.method == 'post':
@@ -164,6 +190,9 @@
         return has_errors
 
     def clear_errors(self):
+        """Ensure that all components of the form have parsed themselves.
+        Clear any errors that might have occured during parsing.
+        """
         request = get_request()
         for widget in self.get_all_widgets():
             widget.clear_error(request)
@@ -172,9 +201,8 @@
         """() -> string | bool
 
         Get the name of the submit button that was used to submit the
-        current form.  If the form is submitted but not by a button added by
-        add_submit() then return True.  Otherwise, return False.
-
+        current form.  If the form is submitted but not by any known
+        SubmitWidget then return True.  Otherwise, return False.
         """
         request = get_request()
         for button in self.submit_widgets:
@@ -187,6 +215,9 @@
                 return False
 
     def set_error(self, name, error):
+        """(name : string, error : string)
+        Set the error attribute of the widget named 'name'.
+        """
         widget = self._names.get(name)
         if not widget:
             raise KeyError, "unknown name %r" % name
@@ -206,6 +237,8 @@
         else:
             self.widgets.append(widget)
 
+    # convenience methods
+
     def add_submit(self, name, value=None, **kwargs):
         self.add(SubmitWidget, name, value, **kwargs)
 
@@ -290,6 +323,10 @@
     def _render_error_notice(self):
         token_widget = self.get_widget(self.TOKEN_NAME)
         if token_widget is not None and token_widget.has_error():
+            # form tokens are enabled but the token data in the request
+            # does not match anything in the session.  It could be an
+            # a cross-site attack but most likely the back button has
+            # be used
             return htmltext('<div class="errornotice">'
                             'The form you have submitted is invalid.  Most '
                             'likely it has been successfully submitted once '