From a0b40cc8aa58c557c30840c906fcba3401bb91cf Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 12 Jan 2009 05:12:57 +0000 Subject: - An interface specific to the HTTP verb (GET/PUT/POST/DELETE/HEAD) is attached to each request object on ingress. The HTTP-verb-related interfaces are defined in ``repoze.bfg.interfaces`` and are ``IGETRequest``, ``IPOSTRequest``, ``IPUTRequest``, ``IDELETERequest`` and ``IHEADRequest``. These interfaces can be specified as the ``request_type`` attribute of a bfg view declaration. A view naming a specific HTTP-verb-matching interface will be found only if the view is defined with a request_type that matches the HTTP verb in the incoming request. The more general ``IRequest`` interface can be used as the request_type to catch all requests (and this is indeed the default). All requests implement ``IRequest``. The HTTP-verb-matching idea was pioneered by `repoze.bfg.restrequest `_ . That package is no longer required, but still functions fine. --- CHANGES.txt | 16 ++++++++++++ docs/api/interfaces.rst | 22 +++++++++++++++++ docs/index.rst | 1 + docs/narr/views.rst | 43 ++++++++++++++++++++++++++++++-- repoze/bfg/interfaces.py | 25 ++++++++++++++++++- repoze/bfg/router.py | 9 ++++++- repoze/bfg/tests/test_router.py | 54 +++++++++++++++++++++++++++++++++++++++++ 7 files changed, 166 insertions(+), 4 deletions(-) create mode 100644 docs/api/interfaces.rst diff --git a/CHANGES.txt b/CHANGES.txt index 5bda29b6d..0c5251d3a 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -40,6 +40,22 @@ Features of registries in order to make it possible to call one BFG application from inside another. +- An interface specific to the HTTP verb (GET/PUT/POST/DELETE/HEAD) is + attached to each request object on ingress. The HTTP-verb-related + interfaces are defined in ``repoze.bfg.interfaces`` and are + ``IGETRequest``, ``IPOSTRequest``, ``IPUTRequest``, + ``IDELETERequest`` and ``IHEADRequest``. These interfaces can be + specified as the ``request_type`` attribute of a bfg view + declaration. A view naming a specific HTTP-verb-matching interface + will be found only if the view is defined with a request_type that + matches the HTTP verb in the incoming request. The more general + ``IRequest`` interface can be used as the request_type to catch all + requests (and this is indeed the default). All requests implement + ``IRequest``. The HTTP-verb-matching idea was pioneered by + `repoze.bfg.restrequest + `_ . That + package is no longer required, but still functions fine. + Bug Fixes --------- diff --git a/docs/api/interfaces.rst b/docs/api/interfaces.rst new file mode 100644 index 000000000..e174966a4 --- /dev/null +++ b/docs/api/interfaces.rst @@ -0,0 +1,22 @@ +.. _interfaces_module: + +:mod:`repoze.bfg.interfaces` +============================ + +Request-related interfaces +--------------------------- + +.. automodule:: repoze.bfg.interfaces + + .. autoclass:: IRequest + + .. autoclass:: IGETRequest + + .. autoclass:: IPOSTRequest + + .. autoclass:: IPUTRequest + + .. autoclass:: IDELETERequest + + .. autoclass:: IHEADRequest + diff --git a/docs/index.rst b/docs/index.rst index 917bf8fe4..13edb8a48 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -47,6 +47,7 @@ Per-module :mod:`repoze.bfg` API documentation. :maxdepth: 2 api/events + api/interfaces api/push api/router api/security diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 8cb00767a..3b60d1394 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -264,13 +264,52 @@ View Request Types You can optionally add a *request_type* attribute to your ``view`` declaration, which indicates what "kind" of request the view should be -used for. For example: +used for. If the request type for a request doesn't match the request +type that a view defines as its ``request_type`` argument, that view +won't be called. + +For example: .. code-block:: xml :linenos: + +The above example registers a view for the ``IPOSTRequest`` type, so +it will only be called if the request is a POST request. Even if all +the other specifiers match (e.g. the model type is the class +``.models.Hello``, and the view_name is ``handle_post``), if the +request verb is not POST, it will not be invoked. This provides a way +to ensure that views you write are only called via specific HTTP +verbs. + +The least specific request type is ``repoze.bfg.interfaces.IRequest``. +All requests are guaranteed to implement this request type. It is +also the default request type for views that omit a ``request_type`` +argument. + +:mod:`repoze.bfg` also makes available more specific request types +matching HTTP verbs. When these are specified as a ``request_type`` +for a view, the view will be called only when the request has an HTTP +verb (aka HTTP method) matching the request type. See +:ref:`interfaces_module` for more information about available request +types. + +Custom View Request Types +------------------------- + +You can make use of *custom* view request types. For example: + +.. code-block:: xml + :linenos: + +