[Zope-PAS] New IChallengePlugin interface

[Zachery Bir]

How does this sound as a replacement? Too wordy?

class IChallengePlugin( Interface ):

    """ Initiate a challenge to the user to provide credentials.
    """

    def challenge( request, response, protocol, **kw ):

        """ Assert via the response that credentials will be gathered.

        Takes a REQUEST object, a RESPONSE object and a string
        representing the protocol this plugin operates under. 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. By default, the protocol should be the id of the
        plugin, which means if it fires, it fires alone.

        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.

          - Cause the response object to redirect to another URL (a
            login form page, for instance)

        If the current plugin fires, return protocol.
        Otherwise, return None.
        """