Skip to content
Browse files

- Remove duplication of ``add_route`` API documentation from URL Disp…

…atch

  narrative chapter.
  • Loading branch information...
1 parent 8d7dbf0 commit fb1d641e763ebaf53905f0678469f20f67c621e5 @mcdonc mcdonc committed Jan 30, 2011
Showing with 4 additions and 190 deletions.
  1. +4 −190 docs/narr/urldispatch.rst
View
194 docs/narr/urldispatch.rst
@@ -385,207 +385,21 @@ Route Configuration Arguments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Route configuration ``add_route`` statements may specify a large number of
-arguments.
+arguments. They are documented as part of the API documentation at
+:meth:`pyramid.config.Configurator.add_route`.
Many of these arguments are :term:`route predicate` arguments. A route
predicate argument specifies that some aspect of the request must be true for
the associated route to be considered a match during the route matching
-process.
+process. Examples of route predicate arguments are ``pattern``, ``xhr``, and
+``request_method``.
Other arguments are view configuration related arguments. These only have an
effect when the route configuration names a ``view``.
Other arguments are ``name`` and ``factory``. These arguments represent
neither predicates nor view configuration information.
-**Non-Predicate Arguments**
-
-``name``
- The name of the route, e.g. ``myroute``. This attribute is required. It
- must be unique among all defined routes in a given application.
-
-``factory``
- A Python object (often a function or a class) or a :term:`dotted Python
- name` to such an object that will generate a :app:`Pyramid` resource object
- as the :term:`root` when this route matches. For example,
- ``mypackage.resources.MyFactoryClass``. If this argument is not specified,
- the traversal root factory will be used.
-
-``traverse``
- If you would like to cause the :term:`context` resource to be something
- other than the :term:`root` resource object when this route matches, you
- can spell a traversal pattern as the ``traverse`` argument. This traversal
- pattern will be used as the traversal path: traversal will begin at the
- root object implied by this route (either the global root, or the object
- returned by the ``factory`` associated with this route).
-
- The syntax of the ``traverse`` argument is the same as it is for
- ``pattern``. For example, if the ``pattern`` provided is
- ``articles/{article}/edit``, and the ``traverse`` argument provided is
- ``/{article}``, when a request comes in that causes the route to match in
- such a way that the ``article`` match value is '1' (when the request URI is
- ``/articles/1/edit``), the traversal path will be generated as ``/1``.
- This means that the root object's ``__getitem__`` will be called with the
- name ``1`` during the traversal phase. If the ``1`` object exists, it will
- become the :term:`context` resource of the request.
- :ref:`traversal_chapter` has more information about traversal.
-
- If the traversal path contains segment marker names which are not present
- in the ``pattern`` argument, a runtime error will occur. The ``traverse``
- pattern should not contain segment markers that do not exist in the
- ``pattern``.
-
- A similar combining of routing and traversal is available when a route is
- matched which contains a ``*traverse`` remainder marker in its pattern (see
- :ref:`using_traverse_in_a_route_pattern`). The ``traverse`` argument
- allows you to associate route patterns with an arbitrary traversal path
- without using a ``*traverse`` remainder marker; instead you can use other
- match information.
-
- Note that the ``traverse`` argument is ignored when attached to a route
- that has a ``*traverse`` remainder marker in its pattern.
-
-**Predicate Arguments**
-
-``pattern``
- The path of the route e.g. ``ideas/{idea}``. This argument is required.
- See :ref:`route_pattern_syntax` for information about the syntax of
- route paths. If the path doesn't match the current URL, route matching
- continues.
-
- .. note:: In earlier releases of this framework, this argument existed
- as ``path``. ``path`` continues to work as an alias for
- ``pattern``.
-
-``xhr``
- This value should be either ``True`` or ``False``. If this value is
- specified and is ``True``, the :term:`request` must possess an
- ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header for this route
- to match. This is useful for detecting AJAX requests issued from jQuery,
- Prototype and other Javascript libraries. If this predicate returns
- ``False``, route matching continues.
-
-``request_method``
- A string representing an HTTP method name, e.g. ``GET``, ``POST``,
- ``HEAD``, ``DELETE``, ``PUT``. If this argument is not specified, this
- route will match if the request has *any* request method. If this
- predicate returns ``False``, route matching continues.
-
-``path_info``
- This value represents a regular expression pattern that will be tested
- against the ``PATH_INFO`` WSGI environment variable. If the regex matches,
- this predicate will return ``True``. If this predicate returns ``False``,
- route matching continues.
-
-``request_param``
- This value can be any string. A view declaration with this argument
- ensures that the associated route will only match when the request has a
- key in the ``request.params`` dictionary (an HTTP ``GET`` or ``POST``
- variable) that has a name which matches the supplied value. If the value
- supplied as the argument has a ``=`` sign in it,
- e.g. ``request_params="foo=123"``, then the key (``foo``) must both exist
- in the ``request.params`` dictionary, and the value must match the right
- hand side of the expression (``123``) for the route to "match" the current
- request. If this predicate returns ``False``, route matching continues.
-
-``header``
- This argument represents an HTTP header name or a header name/value pair.
- If the argument contains a ``:`` (colon), it will be considered a
- name/value pair (e.g. ``User-Agent:Mozilla/.*`` or ``Host:localhost``). If
- the value contains a colon, the value portion should be a regular
- expression. If the value does not contain a colon, the entire value will
- be considered to be the header name (e.g. ``If-Modified-Since``). If the
- value evaluates to a header name only without a value, the header specified
- by the name must be present in the request for this predicate to be true.
- If the value evaluates to a header name/value pair, the header specified by
- the name must be present in the request *and* the regular expression
- specified as the value must match the header value. Whether or not the
- value represents a header name or a header name/value pair, the case of the
- header name is not significant. If this predicate returns ``False``, route
- matching continues.
-
-``accept``
- This value represents a match query for one or more mimetypes in the
- ``Accept`` HTTP request header. If this value is specified, it must be in
- one of the following forms: a mimetype match token in the form
- ``text/plain``, a wildcard mimetype match token in the form ``text/*`` or a
- match-all wildcard mimetype match token in the form ``*/*``. If any of the
- forms matches the ``Accept`` header of the request, this predicate will be
- true. If this predicate returns ``False``, route matching continues.
-
-``custom_predicates``
- This value should be a sequence of references to custom predicate
- callables. Use custom predicates when no set of predefined predicates does
- what you need. Custom predicates can be combined with predefined
- predicates as necessary. Each custom predicate callable should accept two
- arguments: ``info`` and ``request`` and should return either ``True`` or
- ``False`` after doing arbitrary evaluation of the context resource and/or
- the request. If all callables return ``True``, the associated route will
- be considered viable for a given request. If any custom predicate returns
- ``False``, route matching continues. See :ref:`custom_route_predicates`
- for more information.
-
-**View-Related Arguments**
-
-``view``
- A Python object or a :term:`dotted Python name` to such an object that will
- be used as a view callable when this route
- matches. e.g. ``mypackage.views.my_view``.
-
-``view_context``
- A class or an :term:`interface` (or a :term:`dotted Python name` to such an
- object) that the :term:`context` resource should possess for the view named
- by the route to be used. If this attribute is not specified, the default
- (``None``) will be used.
-
- If the ``view`` argument is not provided, this argument has no effect.
-
- This attribute can also be spelled as ``for_`` or ``view_for``.
-
-``view_permission``
- The permission name required to invoke the view associated with this route.
- e.g. ``edit``. (see :ref:`using_security_with_urldispatch` for more
- information about permissions).
-
- If the ``view`` attribute is not provided, this argument has no effect.
-
- This argument can also be spelled as ``permission``.
-
-``view_renderer``
- This is either a single string term (e.g. ``json``) or a string implying a
- path or :term:`asset specification` (e.g. ``templates/views.pt``). If the
- renderer value is a single term (does not contain a dot ``.``), the
- specified term will be used to look up a renderer implementation, and that
- renderer implementation will be used to construct a response from the view
- return value. If the renderer term contains a dot (``.``), the specified
- term will be treated as a path, and the filename extension of the last
- element in the path will be used to look up the renderer implementation,
- which will be passed the full path. The renderer implementation will be
- used to construct a response from the view return value. See
- :ref:`views_which_use_a_renderer` for more information.
-
- If the ``view`` argument is not provided, this argument has no effect.
-
- This argument can also be spelled as ``renderer``.
-
-``view_attr``
- The view machinery defaults to using the ``__call__`` method of the view
- callable (or the function itself, if the view callable is a function) to
- obtain a response dictionary. The ``attr`` value allows you to vary the
- method attribute used to obtain the response. For example, if your view
- was a class, and the class has a method named ``index`` and you wanted to
- use this method instead of the class' ``__call__`` method to return the
- response, you'd say ``attr="index"`` in the view configuration for the
- view. This is most useful when the view definition is a class.
-
- If the ``view`` argument is not provided, this argument has no
- effect.
-
-``use_global_views``
- When a request matches this route, and view lookup cannot find a view which
- has a 'route_name' predicate argument that matches the route, try to fall
- back to using a view that otherwise matches the context and request.
-
.. _custom_route_predicates:
Custom Route Predicates

0 comments on commit fb1d641

Please sign in to comment.
Something went wrong with that request. Please try again.