<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Generation — Routes 2.4.1 documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="RESTful services" href="restful.html" />
<link rel="prev" title="Setting up routes" href="setting_up.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="restful.html" title="RESTful services"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="setting_up.html" title="Setting up routes"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Routes 2.4.1 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="generation">
<h1>Generation<a class="headerlink" href="#generation" title="Permalink to this headline">¶</a></h1>
<p>To generate URLs, use the <code class="docutils literal notranslate"><span class="pre">url</span></code> or <code class="docutils literal notranslate"><span class="pre">url_for</span></code> object provided by your
framework. <code class="docutils literal notranslate"><span class="pre">url</span></code> is an instance of Routes <code class="docutils literal notranslate"><span class="pre">URLGenerator</span></code>, while
<code class="docutils literal notranslate"><span class="pre">url_for</span></code> is the older <code class="docutils literal notranslate"><span class="pre">routes.url_for()</span></code> function. <code class="docutils literal notranslate"><span class="pre">url_for</span></code> is being
phased out, so new applications should use <code class="docutils literal notranslate"><span class="pre">url</span></code>.</p>
<p>To generate a named route, specify the route name as a positional argument:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">url</span><span class="p">(</span><span class="s2">"home"</span><span class="p">)</span> <span class="o">=></span> <span class="s2">"/"</span>
</pre></div>
</div>
<p>If the route contains path variables, you must specify values for them using
keyword arguments:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">url</span><span class="p">(</span><span class="s2">"blog"</span><span class="p">,</span> <span class="n">year</span><span class="o">=</span><span class="mi">2008</span><span class="p">,</span> <span class="n">month</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">day</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
</pre></div>
</div>
<p>Non-string values are automatically converted to strings using <code class="docutils literal notranslate"><span class="pre">str()</span></code>.
(This may break with Unicode values containing non-ASCII characters.)</p>
<p>However, if the route defines an extra variable with the same name as a path
variable, the extra variable is used as the default if that keyword is not
specified. Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"archives"</span><span class="p">,</span> <span class="s2">"/archives/</span><span class="si">{id}</span><span class="s2">"</span><span class="p">,</span>
<span class="n">controller</span><span class="o">=</span><span class="s2">"archives"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"view"</span><span class="p">,</span> <span class="nb">id</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="n">url</span><span class="p">(</span><span class="s2">"archives"</span><span class="p">,</span> <span class="nb">id</span><span class="o">=</span><span class="mi">123</span><span class="p">)</span> <span class="o">=></span> <span class="s2">"/archives/123"</span>
<span class="n">url</span><span class="p">(</span><span class="s2">"archives"</span><span class="p">)</span> <span class="o">=></span> <span class="s2">"/archives/1"</span>
</pre></div>
</div>
<p>(The extra variable is <em>not</em> used for matching unless minimization is enabled.)</p>
<p>Any keyword args that do not correspond to path variables will be put in the
query string. Append a “_” if the variable name collides with a Python
keyword:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"archive"</span><span class="p">,</span> <span class="s2">"/archive/</span><span class="si">{year}</span><span class="s2">"</span><span class="p">)</span>
<span class="n">url</span><span class="p">(</span><span class="s2">"archive"</span><span class="p">,</span> <span class="n">year</span><span class="o">=</span><span class="mi">2009</span><span class="p">,</span> <span class="n">font</span><span class="o">=</span><span class="n">large</span><span class="p">)</span> <span class="o">=></span> <span class="s2">"/archive/2009?font=large"</span>
<span class="n">url</span><span class="p">(</span><span class="s2">"archive"</span><span class="p">,</span> <span class="n">year</span><span class="o">=</span><span class="mi">2009</span><span class="p">,</span> <span class="n">print_</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span> <span class="o">=></span> <span class="s2">"/archive/2009?print=1"</span>
</pre></div>
</div>
<p>If the application is mounted at a subdirectory of the URL space,
all generated URLs will have the application prefix. The application prefix is
the “SCRIPT_NAME” variable in the request’s WSGI environment.</p>
<p>If the positional argument corresponds to no named route, it is assumed to be a
literal URL. The application’s mount point is prefixed to it, and keyword args
are converted to query parameters:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">url</span><span class="p">(</span><span class="s2">"/search"</span><span class="p">,</span> <span class="n">q</span><span class="o">=</span><span class="s2">"My question"</span><span class="p">)</span> <span class="o">=></span> <span class="s2">"/search?q=My+question"</span>
</pre></div>
</div>
<p>If there is no positional argument, Routes will use the keyword args to choose
a route. The first route that has all path variables specified by keyword args
and the fewest number of extra variables not overridden by keyword args will be
chosen. This was common in older versions of Routes but can cause application
bugs if an unexpected route is chosen, so using route names is much preferable
because that guarantees only the named route will be chosen. The most common
use for unnamed generation is when you have a seldom-used controller with a lot
of ad hoc methods; e.g., <code class="docutils literal notranslate"><span class="pre">url(controller="admin",</span> <span class="pre">action="session")</span></code>.</p>
<p>An exception is raised if no route corresponds to the arguments. The exception
is <code class="docutils literal notranslate"><span class="pre">routes.util.GenerationException</span></code>. (Prior to Routes 1.9, <code class="docutils literal notranslate"><span class="pre">None</span></code> was
returned instead. It was changed to an exception to prevent invalid blank URLs
from being insered into templates.)</p>
<p>You’ll also get this exception if Python produces a Unicode URL (which could
happen if the route path or a variable value is Unicode). Routes generates
only <code class="docutils literal notranslate"><span class="pre">str</span></code> URLs.</p>
<p>The following keyword args are special:</p>
<blockquote>
<div><p>anchor</p>
<blockquote>
<div><p>Specifies the URL anchor (the part to the right of “#”).</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">url</span><span class="p">(</span><span class="s2">"home"</span><span class="p">,</span> <span class="s2">"summary"</span><span class="p">)</span> <span class="o">=></span> <span class="s2">"/#summary"</span>
</pre></div>
</div>
</div></blockquote>
<p>host</p>
<blockquote>
<div>Make the URL fully qualified and override the host (domain).</div></blockquote>
<p>protocol</p>
<blockquote>
<div>Make the URL fully qualified and override the protocol (e.g., “ftp”).</div></blockquote>
<p>qualified</p>
<blockquote>
<div>Make the URL fully qualified (i.e., add “protocol://host:port” prefix).</div></blockquote>
<p>sub_domain</p>
<blockquote>
<div>See “Generating URLs with subdomains” below.</div></blockquote>
</div></blockquote>
<p>The syntax in this section is the same for both <code class="docutils literal notranslate"><span class="pre">url</span></code> and <code class="docutils literal notranslate"><span class="pre">url_for</span></code>.</p>
<p><em>New in Routes 1.10: ``url`` and the ``URLGenerator`` class behind it.</em></p>
<div class="section" id="generating-routes-based-on-the-current-url">
<h2>Generating routes based on the current URL<a class="headerlink" href="#generating-routes-based-on-the-current-url" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">url.current()</span></code> returns the URL of the current request, without the query
string. This is called “route memory”, and works only if the RoutesMiddleware
is in the middleware stack. Keyword arguments override path variables or are
put on the query string.</p>
<p><code class="docutils literal notranslate"><span class="pre">url_for</span></code> combines the behavior of <code class="docutils literal notranslate"><span class="pre">url</span></code> and <code class="docutils literal notranslate"><span class="pre">url_current</span></code>. This is
deprecated because nameless routes and route memory have the same syntax, which
can lead to the wrong route being chosen in some cases.</p>
<p>Here’s an example of route memory:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"/archives/</span><span class="si">{year}</span><span class="s2">/</span><span class="si">{month}</span><span class="s2">/</span><span class="si">{day}</span><span class="s2">"</span><span class="p">,</span> <span class="n">year</span><span class="o">=</span><span class="mi">2004</span><span class="p">)</span>
<span class="c1"># Current URL is "/archives/2005/10/4".</span>
<span class="c1"># Routing variables are {"controller": "archives", "action": "view",</span>
<span class="s2">"year"</span><span class="p">:</span> <span class="s2">"2005"</span><span class="p">,</span> <span class="s2">"month"</span><span class="p">:</span> <span class="s2">"10"</span><span class="p">,</span> <span class="s2">"day"</span><span class="p">:</span> <span class="s2">"4"</span><span class="p">}</span>
<span class="n">url</span><span class="o">.</span><span class="n">current</span><span class="p">(</span><span class="n">day</span><span class="o">=</span><span class="mi">6</span><span class="p">)</span> <span class="o">=></span> <span class="s2">"/archives/2005/10/6"</span>
<span class="n">url</span><span class="o">.</span><span class="n">current</span><span class="p">(</span><span class="n">month</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span> <span class="o">=></span> <span class="s2">"/archives/2005/4/4"</span>
<span class="n">url</span><span class="o">.</span><span class="n">current</span><span class="p">()</span> <span class="o">=></span> <span class="s2">"/archives/2005/10/4"</span>
</pre></div>
</div>
<p>Route memory can be disabled globally with <code class="docutils literal notranslate"><span class="pre">map.explicit</span> <span class="pre">=</span> <span class="pre">True</span></code>.</p>
</div>
<div class="section" id="generation-only-routes-aka-static-routes">
<h2>Generation-only routes (aka. static routes)<a class="headerlink" href="#generation-only-routes-aka-static-routes" title="Permalink to this headline">¶</a></h2>
<p>A static route is used only for generation – not matching – and it must be
named. To define a static route, use the argument <code class="docutils literal notranslate"><span class="pre">_static=True</span></code>.</p>
<p>This example provides a convenient way to link to a search:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"google"</span><span class="p">,</span> <span class="s2">"http://google.com/"</span><span class="p">,</span> <span class="n">_static</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">url</span><span class="p">(</span><span class="s2">"google"</span><span class="p">,</span> <span class="n">q</span><span class="o">=</span><span class="s2">"search term"</span><span class="p">)</span> <span class="o">=></span> <span class="s2">"http://google.com/?q=search+term"</span><span class="p">)</span>
</pre></div>
</div>
<p>This example generates a URL to a static image in a Pylons public directory.
Pylons serves the public directory in a way that bypasses Routes, so there’s no
reason to match URLs under it.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"attachment"</span><span class="p">,</span> <span class="s2">"/images/attachments/</span><span class="si">{category}</span><span class="s2">/</span><span class="si">{id}</span><span class="s2">.jpg"</span><span class="p">,</span>
<span class="n">_static</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">url</span><span class="p">(</span><span class="s2">"attachment"</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">"dogs"</span><span class="p">,</span> <span class="nb">id</span><span class="o">=</span><span class="s2">"Mastiff"</span><span class="p">)</span> <span class="o">=></span>
<span class="s2">"/images/attachments/dogs/Mastiff.jpg"</span>
</pre></div>
</div>
<p>Starting in Routes 1.10, static routes are exactly the same as regular routes
except they’re not added to the internal match table. In previous versions of
Routes they could not contain path variables and they had to point to external
URLs.</p>
</div>
<div class="section" id="filter-functions">
<h2>Filter functions<a class="headerlink" href="#filter-functions" title="Permalink to this headline">¶</a></h2>
<p>A filter function modifies how a named route is generated. Don’t confuse it
with a function condition, which is used in matching. A filter function is its
opposite counterpart.</p>
<p>One use case is when you have a <code class="docutils literal notranslate"><span class="pre">story</span></code> object with attributes for year,
month, and day. You don’t want to hardcode these attributes in every <code class="docutils literal notranslate"><span class="pre">url</span></code>
call because the interface may change someday. Instead you pass the story as a
pseudo-argument, and the filter produces the actual generation args. Here’s an
example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Story</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">year</span><span class="p">,</span> <span class="n">month</span><span class="p">,</span> <span class="n">day</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">year</span> <span class="o">=</span> <span class="n">year</span>
<span class="bp">self</span><span class="o">.</span><span class="n">month</span> <span class="o">=</span> <span class="n">month</span>
<span class="bp">self</span><span class="o">.</span><span class="n">day</span> <span class="o">=</span> <span class="n">day</span>
<span class="nd">@staticmethod</span>
<span class="k">def</span> <span class="nf">expand</span><span class="p">(</span><span class="n">kw</span><span class="p">):</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">story</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s2">"story"</span><span class="p">]</span>
<span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
<span class="k">pass</span> <span class="c1"># Don't modify dict if ``story`` key not present.</span>
<span class="k">else</span><span class="p">:</span>
<span class="c1"># Set the actual generation args from the story.</span>
<span class="n">kw</span><span class="p">[</span><span class="s2">"year"</span><span class="p">]</span> <span class="o">=</span> <span class="n">story</span><span class="o">.</span><span class="n">year</span>
<span class="n">kw</span><span class="p">[</span><span class="s2">"month"</span><span class="p">]</span> <span class="o">=</span> <span class="n">story</span><span class="o">.</span><span class="n">month</span>
<span class="n">kw</span><span class="p">[</span><span class="s2">"day"</span><span class="p">]</span> <span class="o">=</span> <span class="n">story</span><span class="o">.</span><span class="n">day</span>
<span class="k">return</span> <span class="n">kw</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"archives"</span><span class="p">,</span> <span class="s2">"/archives/</span><span class="si">{year}</span><span class="s2">/</span><span class="si">{month}</span><span class="s2">/</span><span class="si">{day}</span><span class="s2">"</span><span class="p">,</span>
<span class="n">controller</span><span class="o">=</span><span class="s2">"archives"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"view"</span><span class="p">,</span> <span class="n">_filter</span><span class="o">=</span><span class="n">Story</span><span class="o">.</span><span class="n">expand</span><span class="p">)</span>
<span class="n">my_story</span> <span class="o">=</span> <span class="n">Story</span><span class="p">(</span><span class="mi">2009</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
<span class="n">url</span><span class="p">(</span><span class="s2">"archives"</span><span class="p">,</span> <span class="n">story</span><span class="o">=</span><span class="n">my_story</span><span class="p">)</span> <span class="o">=></span> <span class="s2">"/archives/2009/1/2"</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">_filter</span></code> argument can be any function that takes a dict and returns a
dict. In the example we’ve used a static method of the <code class="docutils literal notranslate"><span class="pre">Story</span></code> class to keep
everything story-related together, but you may prefer to use a standalone
function to keep Routes-related code away from your model.</p>
</div>
<div class="section" id="generating-urls-with-subdomains">
<h2>Generating URLs with subdomains<a class="headerlink" href="#generating-urls-with-subdomains" title="Permalink to this headline">¶</a></h2>
<p>If subdomain support is enabled and the <code class="docutils literal notranslate"><span class="pre">sub_domain</span></code> arg is passed to
<code class="docutils literal notranslate"><span class="pre">url_for</span></code>, Routes ensures the generated route points to that subdomain.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Enable subdomain support.</span>
<span class="nb">map</span><span class="o">.</span><span class="n">sub_domains</span> <span class="o">=</span> <span class="kc">True</span>
<span class="c1"># Ignore the www subdomain.</span>
<span class="nb">map</span><span class="o">.</span><span class="n">sub_domains_ignore</span> <span class="o">=</span> <span class="s2">"www"</span>
<span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"/users/</span><span class="si">{action}</span><span class="s2">"</span><span class="p">)</span>
<span class="c1"># Add a subdomain.</span>
<span class="n">url_for</span><span class="p">(</span><span class="n">action</span><span class="o">=</span><span class="s2">"update"</span><span class="p">,</span> <span class="n">sub_domain</span><span class="o">=</span><span class="s2">"fred"</span><span class="p">)</span> <span class="o">=></span> <span class="s2">"http://fred.example.com/users/update"</span>
<span class="c1"># Delete a subdomain. Assume current URL is fred.example.com.</span>
<span class="n">url_for</span><span class="p">(</span><span class="n">action</span><span class="o">=</span><span class="s2">"new"</span><span class="p">,</span> <span class="n">sub_domain</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span> <span class="o">=></span> <span class="s2">"http://example.com/users/new"</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Generation</a><ul>
<li><a class="reference internal" href="#generating-routes-based-on-the-current-url">Generating routes based on the current URL</a></li>
<li><a class="reference internal" href="#generation-only-routes-aka-static-routes">Generation-only routes (aka. static routes)</a></li>
<li><a class="reference internal" href="#filter-functions">Filter functions</a></li>
<li><a class="reference internal" href="#generating-urls-with-subdomains">Generating URLs with subdomains</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="setting_up.html"
title="previous chapter">Setting up routes</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="restful.html"
title="next chapter">RESTful services</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/generating.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="restful.html" title="RESTful services"
>next</a> |</li>
<li class="right" >
<a href="setting_up.html" title="Setting up routes"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Routes 2.4.1 documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2005-2017, Ben Bangert, Mike Orr, and numerous contributers.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.3.
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
f57b2cbc6bd4a90f10089095b1f7fb88
>
files
>
77
