From 8866e256bf640817692cb16ec0ccc4c642a13b7d Mon Sep 17 00:00:00 2001 From: Fabian Neumann Date: Sat, 17 Aug 2013 16:54:28 +0200 Subject: Document the external URL feature. --- docs/narr/urldispatch.rst | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 310c160c0..34014c9c5 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -105,6 +105,7 @@ to using the previous combination of ``add_route`` and ``add_view``. .. _route_pattern_syntax: + Route Pattern Syntax ~~~~~~~~~~~~~~~~~~~~ @@ -754,9 +755,43 @@ other non-``name`` and non-``pattern`` arguments to exception to this rule is use of the ``pregenerator`` argument, which is not ignored when ``static`` is ``True``. +:ref:`External routes ` are implicitely static. + .. versionadded:: 1.1 the ``static`` argument to :meth:`~pyramid.config.Configurator.add_route` +.. _external_route_narr: + + +External Routes +--------------- + +.. versionadded:: 1.5 + +Route patterns that are valid URLs, are treated as external routes. Like +:ref:`static routes ` they are useful for URL generation +purposes only and are never considered for matching at request time. + +.. code-block:: python + :linenos: + + >>> config = Configurator() + >>> config.add_route('youtube', 'https://youtube.com/watch/{video_id}') + ... + >>> request.route_url('youtube', video_id='oHg5SJYRHA0') + >>> "https://youtube.com/watch/oHg5SJYRHA0" + +All pattern replacements and calls to +:meth:`pyramid.request.Request.route_url` will work as expected. Note that +:meth:`pyramid.request.Request.route_path` will also just return the external +URLs path part. + +.. note:: + + The external URL feature is implemented with a :term:`pregenerator` so you + cannot use both with the same route. + + .. index:: single: redirecting to slash-appended routes -- cgit v1.2.3