Current File : //usr/share/doc/python3-routes/html/setting_up.html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Setting up routes — Routes 2.5.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Generation" href="generating.html" />
<link rel="prev" title="Introduction" href="introduction.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="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="generating.html" title="Generation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="introduction.html" title="Introduction"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Routes 2.5.0 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Setting up routes</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="setting-up-routes">
<h1>Setting up routes<a class="headerlink" href="#setting-up-routes" title="Permalink to this headline">¶</a></h1>
<p>It is assumed that you are using a framework that has preconfigured Routes for
you. In Pylons, you define your routes in the <code class="docutils literal notranslate"><span class="pre">make_map</span></code> function in your
<em>myapp/config/routing.py</em> module. Here is a typical configuration:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kn">from</span> <span class="nn">routes</span> <span class="kn">import</span> <span class="n">Mapper</span>
<span class="linenos">2</span><span class="nb">map</span> <span class="o">=</span> <span class="n">Mapper</span><span class="p">()</span>
<span class="linenos">3</span><span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="kc">None</span><span class="p">,</span> <span class="s2">"/error/</span><span class="si">{action}</span><span class="s2">/</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">"error"</span><span class="p">)</span>
<span class="linenos">4</span><span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"home"</span><span class="p">,</span> <span class="s2">"/"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s2">"main"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"index"</span><span class="p">)</span>
<span class="linenos">5</span><span class="c1"># ADD CUSTOM ROUTES HERE</span>
<span class="linenos">6</span><span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="kc">None</span><span class="p">,</span> <span class="s2">"/</span><span class="si">{controller}</span><span class="s2">/</span><span class="si">{action}</span><span class="s2">"</span><span class="p">)</span>
<span class="linenos">7</span><span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="kc">None</span><span class="p">,</span> <span class="s2">"/</span><span class="si">{controller}</span><span class="s2">/</span><span class="si">{action}</span><span class="s2">/</span><span class="si">{id}</span><span class="s2">"</span><span class="p">)</span>
</pre></div>
</div>
<p>Lines 1 and 2 create a mapper.</p>
<p>Line 3 matches any three-component route that starts with “/error”, and sets
the “controller” variable to a constant, so that a URL
“/error/images/arrow.jpg” would produce:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="s2">"controller"</span><span class="p">:</span> <span class="s2">"error"</span><span class="p">,</span> <span class="s2">"action"</span><span class="p">:</span> <span class="s2">"images"</span><span class="p">,</span> <span class="s2">"id"</span><span class="p">:</span> <span class="s2">"arrow.jpg"</span><span class="p">}</span>
</pre></div>
</div>
<p>Line 4 matches the single URL “/”, and sets both the controller and action to
constants. It also has a route name “home”, which can be used in generation.
(The other routes have <code class="docutils literal notranslate"><span class="pre">None</span></code> instead of a name, so they don’t have names.
It’s recommended to name all routes that may be used in generation, but it’s
not necessary to name other routes.)</p>
<p>Line 6 matches any two-component URL, and line 7 matches any 3-component URL.
These are used as catchall routes if we’re too lazy to define a separate route
for every action. If you <em>have</em> defined a route for every action, you can
delete these two routes.</p>
<p>Note that a URL “/error/images/arrow.jpg” could match both line 3 and line 7.
The mapper resolves this by trying routes in the order defined, so this URL
would match line 3.</p>
<p>If no routes match the URL, the mapper returns a “match failed” condition,
which is seen in Pylons as HTTP 404 “Not Found”.</p>
<p>Here are some more examples of valid routes:</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">"/feeds/</span><span class="si">{category}</span><span class="s2">/atom.xml"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s2">"feeds"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"atom"</span><span class="p">)</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"history"</span><span class="p">,</span> <span class="s2">"/archives/by_eon/</span><span class="si">{century}</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">"aggregate"</span><span class="p">)</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"article"</span><span class="p">,</span> <span class="s2">"/article/</span><span class="si">{section}</span><span class="s2">/</span><span class="si">{slug}</span><span class="s2">/</span><span class="si">{page}</span><span class="s2">.html"</span><span class="p">,</span>
<span class="n">controller</span><span class="o">=</span><span class="s2">"article"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"view"</span><span class="p">)</span>
</pre></div>
</div>
<p>Extra variables may be any Python type, not just strings. However, if the
route is used in generation, <code class="docutils literal notranslate"><span class="pre">str()</span></code> will be called on the value unless
the generation call specifies an overriding value.</p>
<p>Other argument syntaxes are allowed for compatibility with earlier versions of
Routes. These are described in the <code class="docutils literal notranslate"><span class="pre">Backward</span> <span class="pre">Compatibility</span></code> section.</p>
<p>Route paths should always begin with a slash (“/”). Earlier versions of
Routes allowed slashless paths, but their behavior now is undefined.</p>
<section id="requirements">
<h2>Requirements<a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h2>
<p>It’s possible to restrict a path variable to a regular expression; e.g., to
match only a numeric component or a restricted choice of words. There are two
syntaxes for this: inline and the <code class="docutils literal notranslate"><span class="pre">requirements</span></code> argument. An inline
requirement looks like this:</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="sa">R</span><span class="s2">"/blog/{id:\d+}"</span><span class="p">)</span>
<span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="sa">R</span><span class="s2">"/download/{platform:windows|mac}/</span><span class="si">{filename}</span><span class="s2">"</span><span class="p">)</span>
</pre></div>
</div>
<p>This matches “/blog/123” but not “/blog/12A”. The equivalent <code class="docutils literal notranslate"><span class="pre">requirements</span></code>
syntax is:</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">"/blog/</span><span class="si">{id}</span><span class="s2">"</span><span class="p">,</span> <span class="n">requirements</span><span class="o">=</span><span class="p">{</span><span class="s2">"id"</span><span class="p">:</span> <span class="sa">R</span><span class="s2">"\d+"</span><span class="p">}</span>
<span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"/download/</span><span class="si">{platform}</span><span class="s2">/</span><span class="si">{filename}</span><span class="s2">"</span><span class="p">,</span>
<span class="n">requirements</span><span class="o">=</span><span class="p">{</span><span class="s2">"platform"</span><span class="p">:</span> <span class="sa">R</span><span class="s2">"windows|mac"</span><span class="p">})</span>
</pre></div>
</div>
<p>Note the use of raw string syntax (<code class="docutils literal notranslate"><span class="pre">R""</span></code>) for regexes which might contain
backslashes. Without the R you’d have to double every backslash.</p>
<p>Another 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="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">year</span><span class="o">=</span><span class="mi">2004</span><span class="p">,</span>
<span class="n">requirements</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">year</span><span class="o">=</span><span class="sa">R</span><span class="s2">"\d{2,4}"</span><span class="p">,</span> <span class="n">month</span><span class="o">=</span><span class="sa">R</span><span class="s2">"\d{1,2}"</span><span class="p">))</span>
</pre></div>
</div>
<p>The inline syntax was added in Routes (XXX 1.10?? not in changelog). Previous
versions had only the <code class="docutils literal notranslate"><span class="pre">requirements</span></code> argument. Two advantages of the
<code class="docutils literal notranslate"><span class="pre">requirements</span></code> argument are that if you have several variables with identical
requirements, you can set one variable or even the entire argument to a
global:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">NUMERIC</span> <span class="o">=</span> <span class="sa">R</span><span class="s2">"\d+"</span>
<span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">requirements</span><span class="o">=</span><span class="p">{</span><span class="s2">"id"</span><span class="p">:</span> <span class="n">NUMERIC</span><span class="p">})</span>
<span class="n">ARTICLE_REQS</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"year"</span><span class="p">:</span> <span class="sa">R</span><span class="s2">"\d\d\d\d"</span><span class="p">,</span> <span class="s2">"month"</span><span class="p">:</span> <span class="sa">R</span><span class="s2">"\d\d"</span><span class="p">,</span> <span class="s2">"day"</span><span class="p">:</span> <span class="sa">R</span><span class="s2">"\d\d"</span><span class="p">}</span>
<span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">requirements</span><span class="o">=</span><span class="n">ARTICLE_REQS</span><span class="p">)</span>
</pre></div>
</div>
<p>Because the argument <code class="docutils literal notranslate"><span class="pre">requirements</span></code> is reserved, you can’t define a routing
variable by that name.</p>
</section>
<section id="magic-path-info">
<h2>Magic path_info<a class="headerlink" href="#magic-path-info" title="Permalink to this headline">¶</a></h2>
<p>If the “path_info” variable is used at the end of the URL, Routes moves
everything preceding it into the “SCRIPT_NAME” environment variable. This is
useful when delegating to another WSGI application that does its own routing:
the subapplication will route on the remainder of the URL rather than the
entire URL. You still
need the “:.*” requirement to capture the following URL components into the
variable.</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="kc">None</span><span class="p">,</span> <span class="s2">"/cards/{path_info:.*}"</span><span class="p">,</span>
<span class="n">controller</span><span class="o">=</span><span class="s2">"main"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"cards"</span><span class="p">)</span>
<span class="c1"># Incoming URL "/cards/diamonds/4.png"</span>
<span class="o">=></span> <span class="p">{</span><span class="s2">"controller"</span><span class="p">:</span> <span class="s2">"main"</span><span class="p">,</span> <span class="n">action</span><span class="p">:</span> <span class="s2">"cards"</span><span class="p">,</span> <span class="s2">"path_info"</span><span class="p">:</span> <span class="s2">"/diamonds/4.png"</span><span class="p">}</span>
<span class="c1"># Second WSGI application sees:</span>
<span class="c1"># SCRIPT_NAME="/cards" PATH_INFO="/diamonds/4.png"</span>
</pre></div>
</div>
<p>This route does not match “/cards” because it requires a following slash.
Add another route to get around this:</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">"cards"</span><span class="p">,</span> <span class="s2">"/cards"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s2">"main"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"cards"</span><span class="p">,</span>
<span class="n">path_info</span><span class="o">=</span><span class="s2">"/"</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>You may think you can combine the two with the following route:</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">"cards"</span><span class="p">,</span> <span class="s2">"/cards{path_info:.*}"</span><span class="p">,</span>
<span class="n">controller</span><span class="o">=</span><span class="s2">"main"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"cards"</span><span class="p">)</span>
</pre></div>
</div>
<p>There are two problems with this, however. One, it would also match
“/cardshark”. Two, Routes 1.10 has a bug: it forgets to take
the suffix off the SCRIPT_NAME.</p>
</div>
<p>A future version of Routes may delegate directly to WSGI applications, but for
now this must be done in the framework. In Pylons, you can do this in a
controller action as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">paste.fileapp</span> <span class="kn">import</span> <span class="n">DirectoryApp</span>
<span class="k">def</span> <span class="nf">cards</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">environ</span><span class="p">,</span> <span class="n">start_response</span><span class="p">):</span>
<span class="n">app</span> <span class="o">=</span> <span class="n">DirectoryApp</span><span class="p">(</span><span class="s2">"/cards-directory"</span><span class="p">)</span>
<span class="k">return</span> <span class="n">app</span><span class="p">(</span><span class="n">environ</span><span class="p">,</span> <span class="n">start_response</span><span class="p">)</span>
</pre></div>
</div>
<p>Or create a fake controller module with a <code class="docutils literal notranslate"><span class="pre">__controller__</span></code> variable set to
the WSGI application:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">paste.fileapp</span> <span class="kn">import</span> <span class="n">DirectoryApp</span>
<span class="n">__controller__</span> <span class="o">=</span> <span class="n">DirectoryApp</span><span class="p">(</span><span class="s2">"/cards-directory"</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="conditions">
<h2>Conditions<a class="headerlink" href="#conditions" title="Permalink to this headline">¶</a></h2>
<p>Conditions impose additional constraints on what kinds of requests can match.
The <code class="docutils literal notranslate"><span class="pre">conditions</span></code> argument is a dict with up to three keys:</p>
<blockquote>
<div><p>method</p>
<blockquote>
<div><p>A list of uppercase HTTP methods. The request must be one of the
listed methods.</p>
</div></blockquote>
<p>sub_domain</p>
<blockquote>
<div><p>Can be a list of subdomains, <code class="docutils literal notranslate"><span class="pre">True</span></code>, <code class="docutils literal notranslate"><span class="pre">False</span></code>, or <code class="docutils literal notranslate"><span class="pre">None</span></code>. If a
list, the request must be for one of the specified subdomains. If
<code class="docutils literal notranslate"><span class="pre">True</span></code>, the request must contain a subdomain but it can be anything.
If <code class="docutils literal notranslate"><span class="pre">False</span></code> or <code class="docutils literal notranslate"><span class="pre">None</span></code>, do not match if there’s a subdomain.</p>
<p><em>New in Routes 1.10: ``False`` and ``None`` values.</em></p>
</div></blockquote>
<p>function</p>
<blockquote>
<div><p>A function that evaluates the request. Its signature must be
<code class="docutils literal notranslate"><span class="pre">func(environ,</span> <span class="pre">match_dict)</span> <span class="pre">=></span> <span class="pre">bool</span></code>. It should return true if the
match is successful or false otherwise. The first arg is the WSGI
environment; the second is the routing variables that would be
returned if the match succeeds. The function can modify <code class="docutils literal notranslate"><span class="pre">match_dict</span></code>
in place to affect which variables are returned. This allows a wide
range of transformations.</p>
</div></blockquote>
</div></blockquote>
<p>Examples:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Match only if the HTTP method is "GET" or "HEAD".</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"/user/list"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s2">"user"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"list"</span><span class="p">,</span>
<span class="n">conditions</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">method</span><span class="o">=</span><span class="p">[</span><span class="s2">"GET"</span><span class="p">,</span> <span class="s2">"HEAD"</span><span class="p">]))</span>
<span class="c1"># A sub-domain should be present.</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"/"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s2">"user"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"home"</span><span class="p">,</span>
<span class="n">conditions</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">sub_domain</span><span class="o">=</span><span class="kc">True</span><span class="p">))</span>
<span class="c1"># Sub-domain should be either "fred" or "george".</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"/"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s2">"user"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"home"</span><span class="p">,</span>
<span class="n">conditions</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">sub_domain</span><span class="o">=</span><span class="p">[</span><span class="s2">"fred"</span><span class="p">,</span> <span class="s2">"george"</span><span class="p">]))</span>
<span class="c1"># Put the referrer into the resulting match dictionary.</span>
<span class="c1"># This function always returns true, so it never prevents the match</span>
<span class="c1"># from succeeding.</span>
<span class="k">def</span> <span class="nf">referals</span><span class="p">(</span><span class="n">environ</span><span class="p">,</span> <span class="n">result</span><span class="p">):</span>
<span class="n">result</span><span class="p">[</span><span class="s2">"referer"</span><span class="p">]</span> <span class="o">=</span> <span class="n">environ</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"HTTP_REFERER"</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">True</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"/</span><span class="si">{controller}</span><span class="s2">/</span><span class="si">{action}</span><span class="s2">/</span><span class="si">{id}</span><span class="s2">"</span><span class="p">,</span>
<span class="n">conditions</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">function</span><span class="o">=</span><span class="n">referals</span><span class="p">))</span>
</pre></div>
</div>
</section>
<section id="wildcard-routes">
<h2>Wildcard routes<a class="headerlink" href="#wildcard-routes" title="Permalink to this headline">¶</a></h2>
<p>By default, path variables do not match a slash. This ensures that each
variable will match exactly one component. You can use requirements to
override this:</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">"/static/{filename:.*?}"</span><span class="p">)</span>
</pre></div>
</div>
<p>This matches “/static/foo.jpg”, “/static/bar/foo.jpg”, etc.</p>
<p>Beware that careless regexes may eat the entire rest of the URL and cause
components to the right of it not to match:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># OK because the following component is static and the regex has a "?".</span>
<span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"/static/{filename:.*?}/download"</span><span class="p">)</span>
</pre></div>
</div>
<p>The lesson is to always test wildcard patterns.</p>
</section>
<section id="format-extensions">
<h2>Format extensions<a class="headerlink" href="#format-extensions" title="Permalink to this headline">¶</a></h2>
<p>A path component of <code class="docutils literal notranslate"><span class="pre">{.format}</span></code> will match an optional format extension (e.g.
“.html” or “.json”), setting the format variable to the part after the “.”
(e.g. “html” or “json”) if there is one, or to <code class="docutils literal notranslate"><span class="pre">None</span></code> otherwise. For example:</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="s1">'/entries/</span><span class="si">{id}</span><span class="s1">{.format}'</span><span class="p">)</span>
</pre></div>
</div>
<p>will match “/entries/1” and “/entries/1.mp3”. You can use requirements to
limit which extensions will match, for example:</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="s1">'/entries/{id:\d+}{.format:json}'</span><span class="p">)</span>
</pre></div>
</div>
<p>will match “/entries/1” and “/entries/1.json” but not “/entries/1.mp3”.</p>
<p>As with wildcard routes, it’s important to understand and test this. Without
the <code class="docutils literal notranslate"><span class="pre">\d+</span></code> requirement on the <code class="docutils literal notranslate"><span class="pre">id</span></code> variable above, “/entries/1.mp3” would match
successfully, with the <code class="docutils literal notranslate"><span class="pre">id</span></code> variable capturing “1.mp3”.</p>
<p><em>New in Routes 1.12.</em></p>
</section>
<section id="submappers">
<h2>Submappers<a class="headerlink" href="#submappers" title="Permalink to this headline">¶</a></h2>
<p>A submapper lets you add several similar routes
without having to repeat identical keyword arguments. There are two syntaxes,
one using a Python <code class="docutils literal notranslate"><span class="pre">with</span></code> block, and the other avoiding it.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Using 'with'</span>
<span class="k">with</span> <span class="nb">map</span><span class="o">.</span><span class="n">submapper</span><span class="p">(</span><span class="n">controller</span><span class="o">=</span><span class="s2">"home"</span><span class="p">)</span> <span class="k">as</span> <span class="n">m</span><span class="p">:</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"home"</span><span class="p">,</span> <span class="s2">"/"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"splash"</span><span class="p">)</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"index"</span><span class="p">,</span> <span class="s2">"/index"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"index"</span><span class="p">)</span>
<span class="c1"># Not using 'with'</span>
<span class="n">m</span> <span class="o">=</span> <span class="nb">map</span><span class="o">.</span><span class="n">submapper</span><span class="p">(</span><span class="n">controller</span><span class="o">=</span><span class="s2">"home"</span><span class="p">)</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"home"</span><span class="p">,</span> <span class="s2">"/"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"splash"</span><span class="p">)</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"index"</span><span class="p">,</span> <span class="s2">"/index"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"index"</span><span class="p">)</span>
<span class="c1"># Both of these syntaxes create the following routes::</span>
<span class="c1"># "/" => {"controller": "home", action="splash"}</span>
<span class="c1"># "/index" => {"controller": "home", action="index"}</span>
</pre></div>
</div>
<p>You can also specify a common path prefix for your routes:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">map</span><span class="o">.</span><span class="n">submapper</span><span class="p">(</span><span class="n">path_prefix</span><span class="o">=</span><span class="s2">"/admin"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s2">"admin"</span><span class="p">)</span> <span class="k">as</span> <span class="n">m</span><span class="p">:</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"admin_users"</span><span class="p">,</span> <span class="s2">"/users"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"users"</span><span class="p">)</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"admin_databases"</span><span class="p">,</span> <span class="s2">"/databases"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"databases"</span><span class="p">)</span>
<span class="c1"># /admin/users => {"controller": "admin", "action": "users"}</span>
<span class="c1"># /admin/databases => {"controller": "admin", "action": "databases"}</span>
</pre></div>
</div>
<p>All arguments to <code class="docutils literal notranslate"><span class="pre">.submapper</span></code> must be keyword arguments.</p>
<p>The submapper is <em>not</em> a complete mapper. It’s just a temporary object
with a <code class="docutils literal notranslate"><span class="pre">.connect</span></code> method that adds routes to the mapper it was spawned
from.</p>
<p><em>New in Routes 1.11.</em></p>
</section>
<section id="submapper-helpers">
<h2>Submapper helpers<a class="headerlink" href="#submapper-helpers" title="Permalink to this headline">¶</a></h2>
<p>Submappers contain a number of helpers that further simplify routing
configuration. This:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">map</span><span class="o">.</span><span class="n">submapper</span><span class="p">(</span><span class="n">controller</span><span class="o">=</span><span class="s2">"home"</span><span class="p">)</span> <span class="k">as</span> <span class="n">m</span><span class="p">:</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"home"</span><span class="p">,</span> <span class="s2">"/"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"splash"</span><span class="p">)</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"index"</span><span class="p">,</span> <span class="s2">"/index"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"index"</span><span class="p">)</span>
</pre></div>
</div>
<p>can be written:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">map</span><span class="o">.</span><span class="n">submapper</span><span class="p">(</span><span class="n">controller</span><span class="o">=</span><span class="s2">"home"</span><span class="p">,</span> <span class="n">path_prefix</span><span class="o">=</span><span class="s2">"/"</span><span class="p">)</span> <span class="k">as</span> <span class="n">m</span><span class="p">:</span>
<span class="n">m</span><span class="o">.</span><span class="n">action</span><span class="p">(</span><span class="s2">"home"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"splash"</span><span class="p">)</span>
<span class="n">m</span><span class="o">.</span><span class="n">link</span><span class="p">(</span><span class="s2">"index"</span><span class="p">)</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">action</span></code> helper generates a route for one or more HTTP methods (‘GET’ is
assumed) at the submapper’s path (‘/’ in the example above). The <code class="docutils literal notranslate"><span class="pre">link</span></code>
helper generates a route at a relative path.</p>
<p>There are specific helpers corresponding to the standard <code class="docutils literal notranslate"><span class="pre">index</span></code>, <code class="docutils literal notranslate"><span class="pre">new</span></code>,
<code class="docutils literal notranslate"><span class="pre">create</span></code>, <code class="docutils literal notranslate"><span class="pre">show</span></code>, <code class="docutils literal notranslate"><span class="pre">edit</span></code>, <code class="docutils literal notranslate"><span class="pre">update</span></code> and <code class="docutils literal notranslate"><span class="pre">delete</span></code> actions.
You can use these directly:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">map</span><span class="o">.</span><span class="n">submapper</span><span class="p">(</span><span class="n">controller</span><span class="o">=</span><span class="s2">"entries"</span><span class="p">,</span> <span class="n">path_prefix</span><span class="o">=</span><span class="s2">"/entries"</span><span class="p">)</span> <span class="k">as</span> <span class="n">entries</span><span class="p">:</span>
<span class="n">entries</span><span class="o">.</span><span class="n">index</span><span class="p">()</span>
<span class="k">with</span> <span class="n">entries</span><span class="o">.</span><span class="n">submapper</span><span class="p">(</span><span class="n">path_prefix</span><span class="o">=</span><span class="s2">"/</span><span class="si">{id}</span><span class="s2">"</span><span class="p">)</span> <span class="k">as</span> <span class="n">entry</span><span class="p">:</span>
<span class="n">entry</span><span class="o">.</span><span class="n">show</span><span class="p">()</span>
</pre></div>
</div>
<p>or indirectly:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">map</span><span class="o">.</span><span class="n">submapper</span><span class="p">(</span><span class="n">controller</span><span class="o">=</span><span class="s2">"entries"</span><span class="p">,</span> <span class="n">path_prefix</span><span class="o">=</span><span class="s2">"/entries"</span><span class="p">,</span>
<span class="n">actions</span><span class="o">=</span><span class="p">[</span><span class="s2">"index"</span><span class="p">])</span> <span class="k">as</span> <span class="n">entries</span><span class="p">:</span>
<span class="n">entries</span><span class="o">.</span><span class="n">submapper</span><span class="p">(</span><span class="n">path_prefix</span><span class="o">=</span><span class="s2">"/</span><span class="si">{id}</span><span class="s2">"</span><span class="p">,</span> <span class="n">actions</span><span class="o">=</span><span class="p">[</span><span class="s2">"show"</span><span class="p">])</span>
</pre></div>
</div>
<p>Collection/member submappers nested in this way are common enough that there is
helper for this too:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">map</span><span class="o">.</span><span class="n">collection</span><span class="p">(</span><span class="n">collection_name</span><span class="o">=</span><span class="s2">"entries"</span><span class="p">,</span> <span class="n">member_name</span><span class="o">=</span><span class="s2">"entry"</span><span class="p">,</span>
<span class="n">controller</span><span class="o">=</span><span class="s2">"entries"</span><span class="p">,</span>
<span class="n">collection_actions</span><span class="o">=</span><span class="p">[</span><span class="s2">"index"</span><span class="p">],</span> <span class="n">member_actions</span><span class="p">[</span><span class="s2">"show"</span><span class="p">])</span>
</pre></div>
</div>
<p>This returns a submapper instance to which further routes may be added; it has
a <code class="docutils literal notranslate"><span class="pre">member</span></code> property (a nested submapper) to which which member-specific routes
can be added. When <code class="docutils literal notranslate"><span class="pre">collection_actions</span></code> or <code class="docutils literal notranslate"><span class="pre">member_actions</span></code> are omitted,
the full set of actions is generated (see the example under “Printing” below).</p>
<p>See “RESTful services” below for <code class="docutils literal notranslate"><span class="pre">map.resource</span></code>, a precursor to
<code class="docutils literal notranslate"><span class="pre">map.collection</span></code> that does not use submappers.</p>
<p><em>New in Routes 1.12.</em></p>
</section>
<section id="adding-routes-from-a-nested-application">
<h2>Adding routes from a nested application<a class="headerlink" href="#adding-routes-from-a-nested-application" title="Permalink to this headline">¶</a></h2>
<p><em>New in Routes 1.11.</em> Sometimes in nested applications, the child application
gives the parent a list of routes to add to its mapper. These can be added
with the <code class="docutils literal notranslate"><span class="pre">.extend</span></code> method, optionally providing a path prefix:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">routes.route</span> <span class="kn">import</span> <span class="n">Route</span>
<span class="n">routes</span> <span class="o">=</span> <span class="p">[</span>
<span class="n">Route</span><span class="p">(</span><span class="s2">"index"</span><span class="p">,</span> <span class="s2">"/index.html"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s2">"home"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"index"</span><span class="p">),</span>
<span class="p">]</span>
<span class="nb">map</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">routes</span><span class="p">)</span>
<span class="c1"># /index.html => {"controller": "home", "action": "index"}</span>
<span class="nb">map</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">routes</span><span class="p">,</span> <span class="s2">"/subapp"</span><span class="p">)</span>
<span class="c1"># /subapp/index.html => {"controller": "home", "action": "index"}</span>
</pre></div>
</div>
<p>This does not exactly add the route objects to the mapper. It creates
identical new route objects and adds those to the mapper.</p>
<p><em>New in Routes 1.11.</em></p>
</section>
</section>
<div class="clearer"></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="#">Setting up routes</a><ul>
<li><a class="reference internal" href="#requirements">Requirements</a></li>
<li><a class="reference internal" href="#magic-path-info">Magic path_info</a></li>
<li><a class="reference internal" href="#conditions">Conditions</a></li>
<li><a class="reference internal" href="#wildcard-routes">Wildcard routes</a></li>
<li><a class="reference internal" href="#format-extensions">Format extensions</a></li>
<li><a class="reference internal" href="#submappers">Submappers</a></li>
<li><a class="reference internal" href="#submapper-helpers">Submapper helpers</a></li>
<li><a class="reference internal" href="#adding-routes-from-a-nested-application">Adding routes from a nested application</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="introduction.html"
title="previous chapter">Introduction</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="generating.html"
title="next chapter">Generation</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/setting_up.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#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="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="generating.html" title="Generation"
>next</a> |</li>
<li class="right" >
<a href="introduction.html" title="Introduction"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Routes 2.5.0 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Setting up routes</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2005-2022, Ben Bangert, Mike Orr, and numerous contributers.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.3.2.
</div>
</body>
</html>
Mini Shell