diff options
Diffstat (limited to 'docs/narr/urldispatch.rst')
| -rw-r--r-- | docs/narr/urldispatch.rst | 54 |
1 files changed, 27 insertions, 27 deletions
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 7fd94e89e..87efddfad 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -6,7 +6,7 @@ URL Dispatch ============ -The URL dispatch feature of :mod:`pyramid` allows you to either +The URL dispatch feature of :app:`Pyramid` allows you to either augment or replace :term:`traversal` as a :term:`context finding` mechanism, allowing URL pattern matching to have the "first crack" at resolving a given URL to :term:`context` and :term:`view name`. @@ -15,14 +15,14 @@ Although it is a "context-finding" mechanism, ironically, using URL dispatch exclusively allows you to avoid thinking about your application in terms of "contexts" and "view names" entirely. -Many applications don't need :mod:`pyramid` features -- such as +Many applications don't need :app:`Pyramid` features -- such as declarative security via an :term:`authorization policy` -- that benefit from having any visible separation between :term:`context finding` and :term:`view lookup`. To this end, URL dispatch provides a handy syntax that allows you to effectively map URLs *directly* to :term:`view` code in such a way that you needn't think about your application in terms of "context finding" at all. This makes developing -a :mod:`pyramid` application seem more like developing an +a :app:`Pyramid` application seem more like developing an application in a system that is "context-free", such as :term:`Pylons` or :term:`Django`. @@ -49,20 +49,20 @@ High-Level Operational Overview ------------------------------- If route configuration is present in an application, the -:mod:`pyramid` :term:`Router` checks every incoming request against +:app:`Pyramid` :term:`Router` checks every incoming request against an ordered set of URL matching patterns present in a *route map*. If any route pattern matches the information in the :term:`request` -provided to :mod:`pyramid`, a route-specific :term:`context` and +provided to :app:`Pyramid`, a route-specific :term:`context` and :term:`view name` will be generated. In this circumstance, -:mod:`pyramid` will shortcut :term:`traversal`, and will invoke +:app:`Pyramid` will shortcut :term:`traversal`, and will invoke :term:`view lookup` using the context and view name generated by URL dispatch. If the matched route names a :term:`view callable` in its configuration, that view callable will be invoked when view lookup is performed. However, if no route pattern matches the information in the -:term:`request` provided to :mod:`pyramid`, it will fail over to +:term:`request` provided to :app:`Pyramid`, it will fail over to using :term:`traversal` to perform context finding and view lookup. Route Configuration @@ -71,7 +71,7 @@ Route Configuration :term:`Route configuration` is the act of adding a new :term:`route` to an application. A route has a *pattern*, representing a pattern meant to match against the ``PATH_INFO`` portion of a URL, and a -*name*, which is used by developers within a :mod:`pyramid` +*name*, which is used by developers within a :app:`Pyramid` application to uniquely identify a particular route when generating a URL. It also optionally has a ``factory``, a set of :term:`route predicate` parameters, and a set of :term:`view` parameters. @@ -153,7 +153,7 @@ Route View Callable Registration and Lookup Details !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! When a ``view`` attribute is attached to a route configuration, -:mod:`pyramid` ensures that a :term:`view configuration` is +:app:`Pyramid` ensures that a :term:`view configuration` is registered that will always be found when the route pattern is matched during a request. To do so: @@ -175,8 +175,8 @@ during a request. To do so: to service requests that match the route pattern. In this way, we supply a shortcut to the developer. Under the hood, -:mod:`pyramid` still consumes the :term:`context finding` and -:term:`view lookup` subsystems provided by :mod:`pyramid`, but in a +:app:`Pyramid` still consumes the :term:`context finding` and +:term:`view lookup` subsystems provided by :app:`Pyramid`, but in a way which does not require that a developer understand either of them if he doesn't want or need to. It also means that we can allow a developer to combine :term:`URL dispatch` and :term:`traversal` in @@ -190,7 +190,7 @@ various exceptional cases as documented in :ref:`hybrid_chapter`. Route Pattern Syntax ~~~~~~~~~~~~~~~~~~~~ -The syntax of the pattern matching language used by :mod:`pyramid` +The syntax of the pattern matching language used by :app:`Pyramid` URL dispatch in the *pattern* argument is straightforward; it is close to that of the :term:`Routes` system used by :term:`Pylons`. @@ -391,7 +391,7 @@ possible to supply a different :term:`context` object to the view related to each particular route. Supplying a different context for each route is useful when you're -trying to use a :mod:`pyramid` :term:`authorization policy` to +trying to use a :app:`Pyramid` :term:`authorization policy` to provide declarative "context-sensitive" security checks; each context can maintain a separate :term:`ACL`, as in :ref:`using_security_with_urldispatch`. It is also useful when you @@ -425,7 +425,7 @@ represent neither predicates nor view configuration information. ``factory`` A Python object (often a function or a class) or a :term:`dotted Python name` to such an object that will generate a - :mod:`pyramid` :term:`context` object when this route + :app:`Pyramid` :term:`context` object when this route matches. For example, ``mypackage.models.MyFactoryClass``. If this argument is not specified, the traversal root factory will be used. @@ -737,9 +737,9 @@ The main purpose of route configuration is to match (or not match) the ``PATH_INFO`` present in the WSGI environment provided during a request against a URL path pattern. -The way that :mod:`pyramid` does this is very simple. When a +The way that :app:`Pyramid` does this is very simple. When a request enters the system, for each route configuration declaration -present in the system, :mod:`pyramid` checks the ``PATH_INFO`` +present in the system, :app:`Pyramid` checks the ``PATH_INFO`` against the pattern declared. If any route matches, the route matching process stops. The @@ -762,7 +762,7 @@ skipped and route matching continues through the ordered set of routes. If no route matches after all route patterns are exhausted, -:mod:`pyramid` falls back to :term:`traversal` to do :term:`context +:app:`Pyramid` falls back to :term:`traversal` to do :term:`context finding` and :term:`view lookup`. .. index:: @@ -865,7 +865,7 @@ might add to your application: config.add_route('user', 'users/:user', view='mypackage.views.user_view') config.add_route('tag', 'tags/:tags', view='mypackage.views.tag_view') -The above configuration will allow :mod:`pyramid` to service URLs +The above configuration will allow :app:`Pyramid` to service URLs in these forms: .. code-block:: text @@ -1064,10 +1064,10 @@ general description of how to configure a not found view. Custom Not Found View With Slash Appended Routes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There can only be one :term:`Not Found view` in any :mod:`pyramid` +There can only be one :term:`Not Found view` in any :app:`Pyramid` application. Even if you use :func:`pyramid.view.append_slash_notfound_view` as the Not Found -view, :mod:`pyramid` still must generate a ``404 Not Found`` +view, :app:`Pyramid` still must generate a ``404 Not Found`` response when it cannot redirect to a slash-appended URL; this not found response will be visible to site users. @@ -1115,7 +1115,7 @@ 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; the subscriber can do this work. -For example, let's say you have a ``mypackage`` :mod:`pyramid` +For example, let's say you have a ``mypackage`` :app:`Pyramid` application package that uses SQLAlchemy, and you'd like the current SQLAlchemy database session to be removed after each request. Put the following in the ``mypackage.run`` module: @@ -1151,7 +1151,7 @@ every request). .. note:: This is only an example. In particular, it is not necessary to cause ``DBSession.remove`` to be called as the result of an event listener in an application generated from any - :mod:`pyramid` paster template, because these all use the + :app:`Pyramid` paster template, because these all use the ``repoze.tm2`` middleware. The cleanup done by ``DBSession.remove`` is unnecessary when ``repoze.tm2`` middleware is in the WSGI pipeline. @@ -1161,10 +1161,10 @@ every request). .. _using_security_with_urldispatch: -Using :mod:`pyramid` Security With URL Dispatch +Using :app:`Pyramid` Security With URL Dispatch -------------------------------------------------- -:mod:`pyramid` provides its own security framework which consults an +:app:`Pyramid` provides its own security framework which consults an :term:`authorization policy` before allowing any application code to be called. This framework operates in terms of an access control list, which is stored as an ``__acl__`` attribute of a context object. @@ -1186,7 +1186,7 @@ Such a ``factory`` might look like so: self.__acl__ = [ (Allow, 'editor', 'view') ] If the route ``archives/:article`` is matched, and the article number -is ``1``, :mod:`pyramid` will generate an ``Article`` +is ``1``, :app:`Pyramid` 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 than inspect the routes match dict to see if the ``article`` argument @@ -1194,11 +1194,11 @@ matches a particular string; our sample ``Article`` factory class is not very ambitious. .. note:: See :ref:`security_chapter` for more information about - :mod:`pyramid` security and ACLs. + :app:`Pyramid` security and ACLs. References ---------- A tutorial showing how :term:`URL dispatch` can be used to create a -:mod:`pyramid` application exists in :ref:`bfg_sql_wiki_tutorial`. +:app:`Pyramid` application exists in :ref:`bfg_sql_wiki_tutorial`. |