Added definitions to the base browser publishing process.

This allows us to move toward a greater interoperability with other systems.
This change will trigger a serie for changes in the zope packages, mainly in zope.publisher.

2 files changed, 220 insertions, 18 deletions

diff --git a/src/zope/browser/README.txt b/src/zope/browser/README.txt
index 5bb99b4..fee3c4e 100644
--- a/src/zope/browser/README.txt
+++ b/src/zope/browser/README.txt
@@ -1,5 +1,105 @@
+IRequest
+========
+
+Requests are the fundamental entry point of a browser request.
+
+There is not much we can test except that ``IRequest`` is importable
+and an interface:
+
+  >>> from zope.interface import Interface
+  >>> from zope.browser.interfaces import IRequest
+  >>> Interface.providedBy(IRequest)
+  True
+
+
+IResponse
+=========
+
+Naturally, each request made to the server triggers a
+response. Defined by IResponse, it mainly consist in a group of
+headers and, optionnaly, a body.
+
+There is not much we can test except that ``IResponse`` is importable
+and an interface:
+
+  >>> from zope.browser.interfaces import IResponse
+  >>> Interface.providedBy(IResponse)
+  True
+
+
+IPublisher
+==========
+
+The publisher is the component responsable, usually, in transforming a
+request into a response.
+
+There is not much we can test except that ``IPublisher`` is importable
+and an interface:
+
+  >>> from zope.browser.interfaces import IPublisher
+  >>> Interface.providedBy(IPublisher)
+  True
+
+
+
+IPublishingException
+====================
+
+A publishing exception is an exception raised during the publishing
+process. The handling of such exception is therefore often handled
+by the publisher component itself.
+
+  >>> from zope.interface.common.interfaces import IException
+  >>> from zope.browser.interfaces import IPublishingException
+  >>> Interface.providedBy(IPublishingException)
+  True
+  >>> IPublishingException.extends(IException)
+  True
+
+
+IRedirect
+---------
+
+A redirect exception is a publishing exception that interrupt the
+publishing in order to return a redirect-aware response.
+
+  >>> from zope.browser.interfaces import IRedirect
+  >>> Interface.providedBy(IRedirect)
+  True
+  >>> IRedirect.extends(IPublishingException)
+  True
+
+
+INotFound
+---------
+
+An exception meaning that the looked up object has not been found
+during the publishing process.
+
+  >>> from zope.browser.interfaces import INotFound
+  >>> from zope.interface.common.interfaces import ILookupError
+  >>> Interface.providedBy(INotFound)
+  True
+  >>> INotFound.extends(IPublishingException)
+  True
+  >>> INotFound.extends(ILookupError)
+  True
+
+
+IBadRequest
+-----------
+
+Bad request means the request is somehow malformed or erroneous.
+
+  >>> from zope.browser.interfaces import IBadRequest
+  >>> Interface.providedBy(IBadRequest)
+  True
+  >>> IBadRequest.extends(IPublishingException)
+  True
+
+
 IView
------
+=====
 
 Views adapt both a context and a request.
 
@@ -11,8 +111,9 @@ and an interface:
   >>> Interface.providedBy(IView)
   True
 
+
 IBrowserView
--------------
+=============
 
 Browser views are views specialized for requests from a browser (e.g.,
 as distinct from WebDAV, FTP, XML-RPC, etc.).
@@ -20,30 +121,40 @@ as distinct from WebDAV, FTP, XML-RPC, etc.).
 There is not much we can test except that ``IBrowserView`` is importable
 and an interface derived from ``IView``:
 
-  >>> from zope.interface import Interface
   >>> from zope.browser.interfaces import IBrowserView
   >>> Interface.providedBy(IBrowserView)
   True
   >>> IBrowserView.extends(IView)
   True
 
+
+IDefaultViewName
+================
+
+A string that contains the default view name
+
+  >>> from zope.browser.interfaces import IDefaultViewName
+  >>> Interface.providedBy(IDefaultViewName)
+  True
+
+
 IAdding
--------
+=======
 
-Adding views manage how newly-created items get added to containers.
+Adding views manage how newly=created items get added to containers.
 
 There is not much we can test except that ``IAdding`` is importable
 and an interface derived from ``IBrowserView``:
 
-  >>> from zope.interface import Interface
   >>> from zope.browser.interfaces import IAdding
   >>> Interface.providedBy(IBrowserView)
   True
   >>> IAdding.extends(IBrowserView)
   True
 
+
 ITerms
-------
+======
 
 The ``ITerms`` interface is used as a base for ``ISource`` widget
 implementations.  This interfaces get used by ``zope.app.form`` and was
@@ -57,13 +168,13 @@ possible to share them without undesirable dependencies.
 There is not much we can test except that ITerms is importable
 and an interface:
 
-  >>> from zope.interface import Interface
   >>> from zope.browser.interfaces import ITerms
   >>> Interface.providedBy(ITerms)
   True
 
+
 ISystemErrorView
-----------------
+================
 
 Views providing this interface can classify their contexts as system
 errors. These errors can be handled in a special way (e. g. more
@@ -72,7 +183,6 @@ detailed logging).
 There is not much we can test except that ISystemErrorView is importable
 and an interface:
 
-  >>> from zope.interface import Interface
   >>> from zope.browser.interfaces import ISystemErrorView
   >>> Interface.providedBy(ISystemErrorView)
   True
diff --git a/src/zope/browser/interfaces.py b/src/zope/browser/interfaces.py
index a7c0188..9db799e 100644
--- a/src/zope/browser/interfaces.py
+++ b/src/zope/browser/interfaces.py
@@ -11,31 +11,122 @@
 # FOR A PARTICULAR PURPOSE.
 #
 ##############################################################################
-"""Shared dependency less Zope3 brwoser components.
+"""Shared dependency less Zope3 browser components.
 """
 __docformat__ = 'restructuredtext'
 
-from zope.interface import Attribute
-from zope.interface import Interface
+from zope.interface import Attribute, Interface
+from zope.interface.common.interfaces import IException, ILookupError
+
+
+class IRequest(Interface):
+    """A request is a directive sent by a browser to the server,
+    to retrieve a resource. It consists of a location and a set of headers.
+    This information is represented by the environment data.
+    """
+    form = Attribute("parsed GET or POST data")
+    method = Attribute("HTTP method used to query the server.")
+
+    environment = Attribute(
+        "Request environment data. This is a read-only mapping "
+        "from variable name to value.")
+
+
+class IResponse(Interface):
+    """A response is the result of the publishing process.
+    This prototypes a very basic response item, that can be
+    extended for more specific uses.
+    """
+    body = Attribute("body of the response")
+    headers = Attribute("headers of the response")
+
+    def getStatus(as_int=False):
+        """returns the status of the response.
+        """
+
+    def redirect(url, status=None, trusted=False):
+        """Sets the response for a redirect.
+        """
+
+
+class IPublisher(Interface):
+    """A publisher is charged with the task to use a request to publish
+    a resource. This is usually done by returning a response after a
+    'traversal' operation.
+    """
+
+    def publish(request, *args, **kwargs):
+        """Publish a request
+
+        The request is expected to be an IRequest.
+        """
+
+
+class IPublishingException(IException):
+    """A publishing exception is an exception raised during the publishing
+    process. The handling of such exception is therefore handled mainly
+    by the publisher itself, opposed to the other kind of exceptions that
+    are to be handled at another stage or/and another component.
+    """
+
+
+class IRedirect(IPublishingException):
+    """A redirect exception is a publishing exception that interrupt the
+    publishing in order to return a redirect-aware response.
+    """
+
+    location = Attribute("Target location of the redirect")
+
+
+class INotFound(ILookupError, IPublishingException):
+    """An exception meaning that the looked up object has not been found
+    during the publishing process.
+    """
+
+
+class IBadRequest(IPublishingException):
+    """Bad request means the request is somehow malformed or erroneous.
+    It must have the capabilities to expose the error message when printed.
+    """
+
+    def __str__():
+        """Returns the error message.
+        """
+
 
 class IView(Interface):
-    """ Views are multi-adapters for context and request objects.
+    """Views are multi-adapters for context and request objects.
     """
     context = Attribute("The context object the view renders")
     request = Attribute("The request object driving the view")
 
+
 class IBrowserView(IView):
-    """ Views which are specialized for requests from a browser
+    """Views which are specialized for requests from a browser
 
-    o Such views are distinct from those geerated via WebDAV, FTP, XML-RPC,
+    o Such views are distinct from those generated via WebDAV, FTP, XML-RPC,
       etc..
     """
 
+
+class IDefaultViewName(Interface):
+    """A string that contains the default view name
+
+    A default view name is used to select a view when a user hasn't
+    specified one.
+    """
+
+    def __str__():
+        """Returns the default view name.
+        """
+
+
 class IAdding(IBrowserView):
-    """ Multi-adapter interface for views which add items to containers.
+    """Multi-adapter interface for views which add items to containers.
 
     o The 'context' of the view must implement ``zope.container.IContainer``.
     """
+
     def add(content):
         """Add content object to context.
 
@@ -86,7 +177,7 @@ class IAdding(IBrowserView):
 
 
 class ITerms(Interface):
-    """ Adapter providing lookups for vocabulary terms.
+    """Adapter providing lookups for vocabulary terms.
     """
     def getTerm(value):
         """Return an ITitledTokenizedTerm object for the given value
@@ -100,6 +191,7 @@ class ITerms(Interface):
         LookupError is raised if there isn't a value in the source.
         """
 
+
 class ISystemErrorView(Interface):
     """Error views that can classify their contexts as system errors
     """