<!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>Setting up routes — 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="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="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.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="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"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 2 3 4 5 6 7</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">routes</span> <span class="kn">import</span> <span class="n">Mapper</span> <span class="nb">map</span> <span class="o">=</span> <span class="n">Mapper</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="bp">None</span><span class="p">,</span> <span class="s2">"/error/{action}/{id}"</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="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="c1"># ADD CUSTOM ROUTES HERE</span> <span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="bp">None</span><span class="p">,</span> <span class="s2">"/{controller}/{action}"</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="bp">None</span><span class="p">,</span> <span class="s2">"/{controller}/{action}/{id}"</span><span class="p">)</span> </pre></div> </td></tr></table></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> <div class="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> </div> <div class="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="first 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 class="last">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="k">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="k">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> </div> <div class="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>A list of uppercase HTTP methods. The request must be one of the listed methods.</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>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.</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> </div> <div class="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> </div> <div class="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> </div> <div class="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> </div> <div class="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> </div> <div class="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="k">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> </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="#">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>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="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.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>