From dfc2b65c1b6d2f938f68b7868a14d8f9a4faab9e Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 11 Jun 2009 03:15:15 +0000 Subject: Merge unifyroutesandtraversal branch into trunk --- docs/narr/hooks.rst | 73 -------------------------------------- docs/narr/project.rst | 4 +-- docs/narr/traversal.rst | 21 ++++++----- docs/narr/urldispatch.rst | 90 +++++++++++++++++++++-------------------------- docs/narr/urlmapping.rst | 7 ---- 5 files changed, 55 insertions(+), 140 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 533024352..53d6c8c77 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -7,51 +7,6 @@ ZCML "hooks" can be used to influence the behavior of the :mod:`repoze.bfg` framework in various ways. This is an advanced topic; not many people will want or need to do any of these things. -Changing the request factory ----------------------------- - -You may change the class used as the "request factory" from within the -:mod:`repoze.bfg` ``Router`` class (the ``Router`` class turns the -WSGI environment into a "request" object which is used ubiquitously -throughout :mod:`repoze.bfg`). The default "request factory" is the -class ``webob.Request``. You may change it by placing the following -ZCML in your ``configure.zcml`` file. - -.. code-block:: xml - :linenos: - - - -Replace ``helloworld.factories.request_factory`` with the Python -dotted name to the request factory you want to use. Here's some -sample code that implements a minimal request factory: - -.. code-block:: python - - from webob import Request - from repoze.bfg.interfaces import IRequest - - class MyRequest(Request): - implements(IRequest) - - def request_factory(): - return MyRequest - -.. warning:: If you register an ``IRequestFactory`` utility in this - way, you *must* be sure that the factory returns an object that - implements *at least* the ``repoze.bfg.interfaces.IRequest`` - interface. Otherwise all application view lookups will fail (they - will all return a 404 response code). Likewise, if you want to be - able to use method-related interfaces such as ``IGETRequest``, - ``IPOSTRequest``, etc. in your view declarations, the callable - returned by the factory must also do the same introspection of the - environ that the default request factory does and decorate the - returned object to implement one of these interfaces based on the - ``HTTP_METHOD`` present in the environ. Note that the above - example does not do this, so lookups for method-related interfaces - will fail. - Changing the response factory ----------------------------- @@ -164,31 +119,3 @@ code that implements a minimal forbidden view: an alterate forbidden view. For example, it would make sense to return a response with a ``403 Forbidden`` status code. -.. _changing_routes_context_factory: - -Changing the Default Routes Context Factory -------------------------------------------- - -The default Routes "context factory" (the object used to create -context objects when you use ```` statements in your ZCML) is -``repoze.bfg.urldispatch.DefaultRoutesContext``. You may change the -class used as the Routes "context factory" by placing the following -ZCML in your ``configure.zcml`` file. - -.. code-block:: xml - :linenos: - - - -Replace ``helloworld.factories.routes_context_factory`` with the -Python dotted name to the context factory you want to use. Here's -some sample code that implements a minimal context factory: - -.. code-block:: python - :linenos: - - class RoutesContextFactory(object): - def __init__(self, **kw): - self.__dict__.update(kw) - diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 7fb3604de..3de146e8e 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -92,10 +92,10 @@ application's Python code and templates. `_ also exist. Use ``paster create -t bfg_zodb`` to create a project that depends on ZODB. Use ``paster create -t bfg_routesalchemy`` to create a project that depends on - SQLAlchemy and Routes (uses :term:`URL dispatch` instead of + SQLAlchemy and Routes (uses only :term:`URL dispatch` and no :term:`traversal`). Use ``paster create -t bfg_alchemy`` to create a project that depends on SQLAlchemy but *not* Routes (uses - :term:`traversal` instead of :term:`URL dispatch`). + only :term:`traversal` and no :term:`URL dispatch`). Installing your Newly Created Project for Development ----------------------------------------------------- diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 7177432de..4c032952b 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -29,15 +29,18 @@ root object is usually a *mapping* object (such as a Python dictionary). .. note:: If a :term:`root factory` is passed to the :mod:`repoze.bfg` - "make_app" function as the value ``None``, no traversal is - performed. Instead, it's assumed that all URLs will be mapped to - code via :term:`URL dispatch`. No root factory, no traversal. It - is also possible to mix-and-match traversal with URL dispatch. - When both a root factory (and therefore traversal) *and* "routes" - declarations (and therefore url dispatch) are used, the url - dispatch routes are checked first, and if none match, - :mod:`repoze.bfg` will fall back to using traversal to attempt to - map the request to a view. + "make_app" function as the value ``None``, a default root factory + is used. This is most useful when you're using :term:`URL + dispatch` and you don't care very much about traversing any + particular graph to resolve URLs to code. It is also possible to + use traversal and URL dispatch together. When both a root factory + (and therefore traversal) *and* "routes" declarations (and + therefore url dispatch) are used, the url dispatch routes are + checked first, and if none match, :mod:`repoze.bfg` will fall back + to using traversal to attempt to map the request to a view. If the + name ``*traverse`` is in a route's ``path`` pattern, when it is + matched, it is also possible to do traversal *after* a route has + been matched. See :ref:`urldispatch_chapter` for more information. Items contained within the object graph are analogous to the concept of :term:`model` objects used by many other frameworks (and diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index c7d1e2a38..91063fc26 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -16,8 +16,8 @@ which allows you to declaratively map URLs to code. neither concept (controller nor action) exists within :mod:`repoze.bfg`. Instead, when you map a URL pattern to code in bfg, you will map the URL patterm to a :term:`view`. - Once the context and view name are found, the view will be - called with a :term:`context` and a :term:`request`. + Once the context and view are found, the view will be called + with a :term:`context` and a :term:`request`. It often makes a lot of sense to use :term:`URL dispatch` instead of :term:`traversal` in an application that has no natural hierarchy. @@ -54,17 +54,15 @@ acts as a root factory, it is willing to check the requested URL against a *routes map* to find a :term:`context` and a :term:`view` before traversal has a chance to find it first. If a route matches, a :term:`context` is generated and :mod:`repoze.bfg` will call the -:term:`view` specified with the context and the request. - -If no route matches, :mod:`repoze.bfg` will fail over to calling the -root factory callable passed to the application in it's ``make_app`` -function (usually a traversal function). By configuring your ZCML -``route`` statements appropriately, you can mix and match URL dispatch -and traversal in this way. +:term:`view` specified with the context and the request. If no route +matches, :mod:`repoze.bfg` will fail over to calling the :term:`root +factory` callable passed to the application in it's ``make_app`` +function (usually a traversal function). A root factory is not required for purely URL-dispatch-based apps: if -the root factory callable is ``None``, :mod:`repoze.bfg` will return a -NotFound error to the user's browser when no routes match. +the root factory callable is passed as ``None`` to the ``make_app`` +function, :mod:`repoze.bfg` will return a NotFound error to the user's +browser when no routes match. .. note:: See :ref:`modelspy_project_section` for an example of a simple root factory callable that will use traversal. @@ -105,9 +103,8 @@ factory The Python dotted-path name to a function that will generate a :mod:`repoze.bfg` context object when this route matches. - e.g. ``mypackage.models.MyFactoryClass``. By default, a - ``repoze.bfg.urldispatch.DefaultRoutesContext`` object will be - constructed if a factory is not provided. + e.g. ``mypackage.models.MyFactoryClass``. If this argument is not + specified, a default root factory will be used. encoding @@ -267,12 +264,12 @@ Example 3 --------- The context object passed to a view found as the result of URL -dispatch will by default be an instance of the -``repoze.bfg.urldispatch.DefaultRoutesContext`` object. You can -override this behavior by passing in a ``factory`` argument to the -ZCML directive for a particular route. The ``factory`` should be a -callable that accepts arbitrary keyword arguments and returns an -instance of a class that will be the context used by the view. +dispatch will by default be an instance of the object returned by the +default :term:`root factory`. You can override this behavior by +passing in a ``factory`` argument to the ZCML directive for a +particular route. The ``factory`` should be a callable that accepts a +WSGI environment and returns an instance of a class that will be the +context used by the view. An example of using a route with a factory: @@ -288,13 +285,13 @@ An example of using a route with a factory: The above route will manufacture an ``Idea`` model as a context, assuming that ``mypackage.models.Idea`` resolves to a class that -accepts arbitrary key/value pair arguments. +accepts a WSGI environment in its ``__init__``. .. note:: Values prefixed with a period (``.``) for the ``factory`` - and ``provides`` attributes of a ``route`` (such as - ``.models.Idea`` and ``.views.idea_view``) above) mean "relative to - the Python package directory in which this :term:`ZCML` file is - stored". So if the above ``route`` declaration was made inside a + and ``view`` attributes of a ``route`` (such as ``.models.Idea`` + and ``.views.idea_view``) above) mean "relative to the Python + package directory in which this :term:`ZCML` file is stored". So + if the above ``route`` declaration was made inside a ``configure.zcml`` file that lived in the ``hello`` package, you could replace the relative ``.models.Idea`` with the absolute ``hello.models.Idea`` Either the relative or absolute form is @@ -302,14 +299,10 @@ accepts arbitrary key/value pair arguments. form, in case your package's name changes. It's also shorter to type. -All context objects manufactured via URL dispatch will be decorated by -default with the ``repoze.bfg.interfaces.IRoutesContext`` -:term:`interface`. - If no route matches in the above configuration, :mod:`repoze.bfg` will -call the "fallback" ``get_root`` callable provided to it during -``make_app`. If the "fallback" ``get_root`` is None, a ``NotFound`` -error will be raised when no route matches. +call the "fallback" :term:`root factory` callable provided to it +during ``make_app`. If the "fallback" root factory is None, a +``NotFound`` error will be raised when no route matches. .. note:: See :ref:`using_model_interfaces` for more information about how views are found when interfaces are attached to a @@ -338,7 +331,10 @@ The ``.models`` module referred to above might look like so: .. code-block:: python :linenos: - class Article(dict): + class Article(object): + def __init__(self, environ): + self.__dict__.update(environ['repoze.bfg.matchdict']) + def is_root(self): return self['article'] == 'root' @@ -393,8 +389,8 @@ request when a database connection is involved. When of the traversal :term:`root factory`. Often the root factory will insert an object into the WSGI environment that performs some cleanup when its ``__del__`` method is called. When URL dispatch is used, -however, no root factory is required, so sometimes that option is not -open to you. +however, no special root factory is required, so sometimes that option +is not open to you. Instead of putting this cleanup logic in the root factory, however, you can cause a subscriber to be fired when a new request is detected; @@ -439,32 +435,28 @@ Lists, see :ref:`security_chapter` for more information about the :mod:`repoze.bfg` authorization subsystem). A common thing to want to do is to attach an ``__acl__`` to the context object dynamically for declarative security purposes. You can use the ``factory`` argument -that points at a context factory which attaches a custom ``__acl__`` -to an object at its creation time. +that points at a factory which attaches a custom ``__acl__`` to an +object at its creation time. Such a ``factory`` might look like so: .. code-block:: python :linenos: - class Article(dict): - pass - - def article_factory(**kw): - model = Article(**kw) - article = kw.get('article', None) - if article == '1': - model.__acl__ = [ (Allow, 'editor', 'view') ] - return model + class Article(object): + def __init__(self, environ): + matchdict = environ['bfg.routes.matchdict'] + article = matchdict.get('article', None) + if article == '1': + self.__acl__ = [ (Allow, 'editor', 'view') ] If the route ``archives/:article`` is matched, and the article number is ``1``, :mod:`repoze.bfg` will generate an ``Article`` :term:`context` with an ACL on it that allows the ``editor`` principal the ``view`` permission. Obviously you can do more generic things that inspect the routes match dict to see if the ``article`` argument -matches a particular string; our sample ``article_factory`` function -is not very ambitious. Its job could have just as well been done in -the ``Article`` class' constructor, too. +matches a particular string; our sample ``Article`` factory class is +not very ambitious. .. note:: See :ref:`security_chapter` for more information about :mod:`repoze.bfg` security and ACLs. diff --git a/docs/narr/urlmapping.rst b/docs/narr/urlmapping.rst index 3c74d04d9..21f6235f8 100644 --- a/docs/narr/urlmapping.rst +++ b/docs/narr/urlmapping.rst @@ -90,10 +90,3 @@ URL-based dispatch. :mod:`repoze.bfg` provides support for both approaches. You can use either as you see fit. -.. note:: - - Most existng :mod:`repoze.bfg` applications use :term:`traversal` to - map URLs to code. This is mostly due to the :term:`Zope` heritage - of :mod:`repoze.bfg` and because it aids applications that require - highly granular declarative security assertions. - -- cgit v1.2.3