diff options
| -rw-r--r-- | CHANGES.txt | 6 | ||||
| -rw-r--r-- | docs/narr/hybrid.rst | 80 | ||||
| -rw-r--r-- | pyramid/url.py | 18 |
3 files changed, 95 insertions, 9 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 657c50009..cfa77283f 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -4,6 +4,12 @@ Next Release Features -------- +- You can now generate "hybrid" urldispatch/traversal URLs more easily + by using the new ``route_name`` and ``route_kw`` arguments to + ``request.resource_url`` and ``request.resource_path``. See the new section + of the "Combining Traversal and URL Dispatch" documentation chapter entitled + "Hybrid URL Generation". + - It is now possible to escape double braces in Pyramid scaffolds (unescaped, these represent replacement values). You can use ``\{\{a\}\}`` to represent a "bare" ``{{a}}``. See diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst index 1773a6b8c..58d89fc98 100644 --- a/docs/narr/hybrid.rst +++ b/docs/narr/hybrid.rst @@ -549,3 +549,83 @@ be invoked when the request URI is ``/abc/bazbuz``, assuming there is no object contained by the root object with the key ``bazbuz``. A different request URI, such as ``/abc/foo/bar``, would invoke the default ``myproject.views.abc`` view. + +.. index:: + pair: hybrid urls; generating + +.. _generating_hybrid_urls: + +Generating Hybrid URLs +---------------------- + +.. versionadded:: 1.5 + +The :meth:`pyramid.request.Request.resource_url` method and the +:meth:`pyramid.request.Request.resource_path` method both accept optional +keyword arguments that make it easier to generate route-prefixed URLs that +contain paths to traversal resources:``route_name`` and ``route_kw``. + +Any route that has a pattern that contains a ``*remainder`` pattern (any +stararg remainder pattern, such as ``*traverse`` or ``*subpath`` or ``*fred``) +can be used as the target name for ``request.resource_url(..., route_name=)`` +and ``request.resource_path(..., route_name=)``. + +For example, let's imagine you have a route defined in your Pyramid application +like so: + +.. code-block:: python + + config.add_route('mysection', '/mysection*traverse') + +If you'd like to generate the URL ``http://example.com/mysection/a/``, you can +use the following incantation, assuming that the variable ``a`` below points to +a resource that is a child of the root with a ``__name__`` of ``a``: + +.. code-block:: python + + request.resource_url(a, route_name='mysection') + +You can generate only the path portion ``/mysection/a/`` assuming the same: + +.. code-block:: python + + request.resource_path(a, route_name='mysection') + +The path is virtual host aware, so if the ``X-Vhm-Root`` environ variable is +present in the request, and it's set to ``/a``, the above call to +``request.resource_url`` would generate ``http://example.com/mysection/`` +and the above call to ``request.resource_path`` would generate ``/mysection/``. +See :ref:`virtual_root_support` for more information. + +If the route you're trying to use needs simple dynamic part values to be filled +in to succesfully generate the URL, you can pass these as the ``route_kw`` +argument to ``resource_url`` and ``resource_path``. For example, assuming that +the route definition is like so: + +.. code-block:: python + + config.add_route('mysection', '/{id}/mysection*traverse') + +You can pass ``route_kw`` in to fill in ``{id}`` above: + +.. code-block:: python + + request.resource_url(a, route_name='mysection', route_kw={'id':'1'}) + +If you pass ``route_kw`` but do not pass ``route_name``, ``route_kw`` will +be ignored. + +All other values that are normally passable to ``resource_path`` and +``resource_url`` (such as ``query``, ``anchor``, ``host``, ``port``, etc) work +as you might expect in this configuration too. + +If you try to use ``resource_path`` or ``resource_url`` when the ``route_name`` +argument points at a route that does not have a remainder stararg, an error +will not be raised, but the generated URL will not contain any remainder +information either. + +Note that this feature is incompatible with the ``__resource_url__`` feature +(see :ref:`overriding_resource_url_generation`) implemented on resource +objects. Any ``__resource_url__`` supplied by your resource will be ignored +when you pass ``route_name``. + diff --git a/pyramid/url.py b/pyramid/url.py index d8fe997d9..90b8f667f 100644 --- a/pyramid/url.py +++ b/pyramid/url.py @@ -420,6 +420,14 @@ class URLMethodsMixin(object): are also passed, ``app_url`` will take precedence and the values passed for ``scheme``, ``host``, and/or ``port`` will be ignored. + If the ``resource`` passed in has a ``__resource_url__`` method, it + will be used to generate the URL (scheme, host, port, path) for the + base resource which is operated upon by this function. See also + :ref:`overriding_resource_url_generation`. + + .. versionadded:: 1.5 + ``route_name`` and ``route_kw`` + If ``route_name`` is passed, this function will delegate its URL production to the ``route_url`` function. Calling ``resource_url(someresource, 'element1', 'element2', query={'a':1}, @@ -436,7 +444,7 @@ class URLMethodsMixin(object): It is only sensible to pass ``route_name`` if the route being named has a ``*remainder`` stararg value such as ``*traverse``. The remainder - will be ignored in the output otherwise. + value will be ignored in the output otherwise. If ``route_name`` is passed, it is also permissible to pass ``route_kw``, which will passed as additional keyword arguments to @@ -458,14 +466,6 @@ class URLMethodsMixin(object): ``__resource_url__`` method of the resource passed is ignored unconditionally. - The ``route_name`` and ``route_kw`` arguments were added in Pyramid - 1.5. - - If the ``resource`` passed in has a ``__resource_url__`` method, it - will be used to generate the URL (scheme, host, port, path) for the - base resource which is operated upon by this function. See also - :ref:`overriding_resource_url_generation`. - .. note:: If the :term:`resource` used is the result of a :term:`traversal`, it |