[Zope-CVS] CVS: Products/PluggableAuthService/interfaces - plugins.py:1.6

[Zachery Bir]

Update of /cvs-repository/Products/PluggableAuthService/interfaces
In directory cvs.zope.org:/tmp/cvs-serv18289

Modified Files:
	plugins.py 
Log Message:
Refine the interface for IChallengePlugin to not raise exceptions
(since we're dealing with the _results_ of something else already
having raised an exception)


=== Products/PluggableAuthService/interfaces/plugins.py 1.5 => 1.6 ===
--- Products/PluggableAuthService/interfaces/plugins.py:1.5	Tue Sep 14 06:06:56 2004
+++ Products/PluggableAuthService/interfaces/plugins.py	Mon Oct  4 13:41:11 2004
@@ -88,27 +88,33 @@
 class IChallengePlugin( Interface ):
 
     """ Initiate a challenge to the user to provide credentials.
+
+        Challenge plugins have an attribute 'protocol' representing
+        the protocol the plugin operates under, defaulting to None.
+
+        Plugins operating under the same protocol will all be given an
+        attempt to fire. The first plugin of a protocol group that
+        successfully fires establishes the protocol of the overall
+        challenge.
     """
 
-    def challenge( request, response, **kw ):
+    def challenge( request, response ):
+
+        """ Assert via the response that credentials will be gathered.
+
+        Takes a REQUEST object and a RESPONSE object.
+
+        Returns True if it fired, False otherwise.
+
+        Two common ways to initiate a challenge:
+
+          - Add a 'WWW-Authenticate' header to the response object.
+
+            NOTE: add, since the HTTP spec specifically allows for
+            more than one challenge in a given response.
 
-        """ Raise an exception
-        
-        With Zope 2 there are only two ways to initiate a challenge.
-        
-        o raise Unauthorized, message
-        
-        o raise Redirect, url
-        
-        The default challenge response is the raise Unauthorized. 
-        A challenge plugin is therefore only needed if a Redirect 
-        (for example to a login-form) is desired. 
-        
-        The plugin gets request and response so that it can choose to
-        only challenge during certain circumstances. If the plugin
-        does not raise an exception, the next challenge plugin will 
-        be called. If no plugins raise the exception, Unauthorized
-        will be raised.
+          - Cause the response object to redirect to another URL (a
+            login form page, for instance)
         """
 
 class ICredentialsUpdatePlugin( Interface ):