diff options
Diffstat (limited to 'docs/narr/urldispatch.rst')
| -rw-r--r-- | docs/narr/urldispatch.rst | 84 |
1 files changed, 45 insertions, 39 deletions
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index b025ce8d6..cc03acb37 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -96,7 +96,7 @@ registry`. Here's an example: .. versionchanged:: 1.0a4 Prior to 1.0a4, routes allow for a marker starting with a ``:``, for - example ``/prefix/{one}``. Starting in 1.0a4, this style is deprecated + example ``/prefix/:one/:two``. Starting in 1.0a4, this style is deprecated in favor or ``{}`` usage which allows for additional functionality. .. index:: @@ -179,12 +179,12 @@ 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, -: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 -various exceptional cases as documented in :ref:`hybrid_chapter`. +the :term:`context finding` and :term:`view lookup` subsystems +provided by :app:`Pyramid` are still being utilized, but in a way +which does not require a developer to understand either of them in +detail. It also means that we can allow a developer to combine +:term:`URL dispatch` and :term:`traversal` in various exceptional +cases as documented in :ref:`hybrid_chapter`. .. index:: single: route path pattern syntax @@ -263,15 +263,15 @@ To capture both segments, two replacement markers can be used: foo/{name}.{ext} -The literal path ``/foo/biz.html`` will match the above route pattern, and the -match result will be ``{'name': 'biz', 'ext': 'html'}``. This occurs because -the replacement marker ``{name}`` has a literal part of ``.`` between the other -replacement marker ``:ext``. +The literal path ``/foo/biz.html`` will match the above route pattern, +and the match result will be ``{'name': 'biz', 'ext': 'html'}``. This +occurs because the replacement marker ``{name}`` has a literal part of +``.`` (period) between the other replacement marker ``{ext}``. -It is possible to use two replacement markers without any literal characters -between them, for instance ``/{foo}{bar}``. This would be a nonsensical pattern -without specifying a custom regular expression to restrict what a marker -captures. +It is possible to use two replacement markers without any literal +characters between them, for instance ``/{foo}{bar}``. However, this +would be a nonsensical pattern without specifying a custom regular +expression to restrict what each marker captures. Segments must contain at least one character in order to match a segment replacement marker. For example, for the URL ``/abc/``: @@ -281,7 +281,7 @@ segment replacement marker. For example, for the URL ``/abc/``: - ``/{foo}/`` will match. Note that values representing path segments matched with a -``:segment`` match will be url-unquoted and decoded from UTF-8 into +``{segment}`` match will be url-unquoted and decoded from UTF-8 into Unicode within the matchdict. So for instance, the following pattern: @@ -358,7 +358,7 @@ matchdicts: foo/abc/def/a/b/c -> {'baz':'abc', 'bar':'def', 'fizzle': 'a/b/c')} This occurs because the default regular expression for a marker is ``[^/]+`` -which will match everything up to the first ``/``, while ``{filzzle:.*}`` will +which will match everything up to the first ``/``, while ``{fizzle:.*}`` will result in a regular expression match of ``.*`` capturing the remainder into a single value. @@ -368,9 +368,9 @@ a single value. Route Declaration Ordering ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Because route configuration declarations are evaluated in a specific -order when a request enters the system, route configuration -declaration ordering is very important. +Route configuration declarations are evaluated in a specific +order when a request enters the system. As a result, the +order of route configuration declarations is very important. The order that routes declarations are evaluated is the order in which they are added to the application at startup time. This is unlike @@ -390,7 +390,7 @@ be added in the following order: members/abc In such a configuration, the ``members/abc`` pattern would *never* be -matched; this is because the match ordering will always match +matched. This is because the match ordering will always match ``members/{def}`` first; the route configuration with ``members/abc`` will never be evaluated. @@ -417,7 +417,7 @@ found via :term:`view lookup`. factory='myproject.models.root_factory') The factory can either be a Python object or a :term:`dotted Python name` (a -string) which points to such a Python oject, as it is above. +string) which points to such a Python object, as it is above. In this way, each route can use a different factory, making it possible to supply a different :term:`context` object to the view @@ -425,8 +425,8 @@ related to each particular route. Supplying a different context for each route is useful when you're 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 +provide declarative, "context sensitive" security checks; each context +can maintain a separate :term:`ACL`, as documented in :ref:`using_security_with_urldispatch`. It is also useful when you wish to combine URL dispatch with :term:`traversal` as documented within :ref:`hybrid_chapter`. @@ -1075,12 +1075,14 @@ Redirecting to Slash-Appended Routes ------------------------------------ For behavior like Django's ``APPEND_SLASH=True``, use the -:func:`pyramid.view.append_slash_notfound_view` view as the -:term:`Not Found view` in your application. When this view is the Not -Found view (indicating that no view was found), and any routes have -been defined in the configuration of your application, if the value of -``PATH_INFO`` does not already end in a slash, and if the value of -``PATH_INFO`` *plus* a slash matches any route's pattern, it does an +:func:`pyramid.view.append_slash_notfound_view` view as the :term:`Not +Found view` in your application. Defining this view as the :term:`Not +Found view` is a way to automatically redirect requests where the URL +lacks a trailing slash, but requires one to match the proper route. +When configured, along with at least one other route in your +application, this view will be invoked if the value of ``PATH_INFO`` +does not already end in a slash, and if the value of ``PATH_INFO`` +*plus* a slash matches any route's pattern. In this case it does an HTTP redirect to the slash-appended ``PATH_INFO``. Let's use an example, because this behavior is a bit magical. If the @@ -1093,20 +1095,24 @@ your route configuration looks like so: config.add_route('noslash', 'no_slash', view='myproject.views.no_slash') config.add_route('hasslash', 'has_slash/', view='myproject.views.has_slash') +If a request enters the application with the ``PATH_INFO`` +value of ``/has_slash/``, the second route will match. If a request +enters the application with the ``PATH_INFO`` value of ``/has_slash``, +a route *will* be found by the slash-appending not found view. An HTTP +redirect to ``/has_slash/`` will be returned to the user's browser. + If a request enters the application with the ``PATH_INFO`` value of -``/no_slash``, the first route will match. If a request enters the +``/no_slash``, the first route will match. However, if a request enters the application with the ``PATH_INFO`` value of ``/no_slash/``, *no* route -will match, and the slash-appending "not found" view will *not* find a +will match, and the slash-appending not found view will *not* find a matching route with an appended slash. -However, if a request enters the application with the ``PATH_INFO`` -value of ``/has_slash/``, the second route will match. If a request -enters the application with the ``PATH_INFO`` value of ``/has_slash``, -a route *will* be found by the slash appending notfound view. An HTTP -redirect to ``/has_slash/`` will be returned to the user's browser. +.. warning:: -Note that this will *lose* ``POST`` data information (turning it into -a GET), so you shouldn't rely on this to redirect POST requests. + You **should not** rely on this mechanism to redirect ``POST`` requests. + The redirect of the slash-appending not found view will turn a ``POST`` + request into a ``GET``, losing any ``POST`` data in the original + request. To configure the slash-appending not found view in your application, change the application's startup configuration, adding the following stanza: |