<!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>Unicode, Redirects, and More — 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="Routes Changelog" href="changes.html" />
<link rel="prev" title="RESTful services" href="restful.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="changes.html" title="Routes Changelog"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="restful.html" title="RESTful services"
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="unicode-redirects-and-more">
<h1>Unicode, Redirects, and More<a class="headerlink" href="#unicode-redirects-and-more" title="Permalink to this headline">¶</a></h1>
<div class="section" id="unicode">
<h2>Unicode<a class="headerlink" href="#unicode" title="Permalink to this headline">¶</a></h2>
<p>Routes assumes UTF-8 encoding on incoming URLs, and <code class="docutils literal notranslate"><span class="pre">url</span></code> and <code class="docutils literal notranslate"><span class="pre">url_for</span></code>
also generate UTF-8. You can change the encoding with the <code class="docutils literal notranslate"><span class="pre">map.charset</span></code>
attribute:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">map</span><span class="o">.</span><span class="n">charset</span> <span class="o">=</span> <span class="s2">"latin-1"</span>
</pre></div>
</div>
<p>New in Routes 1.10: several bugfixes.</p>
</div>
<div class="section" id="redirect-routes">
<h2>Redirect Routes<a class="headerlink" href="#redirect-routes" title="Permalink to this headline">¶</a></h2>
<p>Redirect routes allow you to specify redirects in the route map, similar to
RewriteRule in an Apache configuration. This avoids the need to define dummy
controller actions just to handle redirects. It’s especially useful when the
URL structure changes and you want to redirect legacy URLs to their new
equivalents. The redirection is done by the Routes middleware, and the WSGI
application is not called.</p>
<p><code class="docutils literal notranslate"><span class="pre">map.redirect</span></code> takes two positional arguments: the route path and the
destination URL. Redirect routes do not have a name. Both paths can contain
variables, and the route path can take inline requirements. Keyword arguments
are the same as <code class="docutils literal notranslate"><span class="pre">map.connect</span></code>, both in regards to extra variables and to route
options.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">map</span><span class="o">.</span><span class="n">redirect</span><span class="p">(</span><span class="s2">"/legacyapp/archives/{url:.*}"</span><span class="p">,</span> <span class="s2">"/archives/</span><span class="si">{url}</span><span class="s2">"</span><span class="p">)</span>
<span class="nb">map</span><span class="o">.</span><span class="n">redirect</span><span class="p">(</span><span class="s2">"/legacyapp/archives/{url:.*}"</span><span class="p">,</span> <span class="s2">"/archives/</span><span class="si">{url}</span><span class="s2">"</span><span class="p">)</span>
</pre></div>
</div>
<p>By default a “302 Found” HTTP status is issued. You can override this with the
<code class="docutils literal notranslate"><span class="pre">_redirect_code</span></code> keyword argument. The value must be an entire status
string.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">map</span><span class="o">.</span><span class="n">redirect</span><span class="p">(</span><span class="s2">"/home/index"</span><span class="p">,</span> <span class="s2">"/"</span><span class="p">,</span> <span class="n">_redirect_code</span><span class="o">=</span><span class="s2">"301 Moved Permanently"</span><span class="p">)</span>
</pre></div>
</div>
<p><em>New in Routes 1.10.</em></p>
</div>
<div class="section" id="printing">
<h2>Printing<a class="headerlink" href="#printing" title="Permalink to this headline">¶</a></h2>
<p>Mappers now have a formatted string representation. In your python shell,
simply print your application’s mapper:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">map</span><span class="o">.</span><span class="n">collection</span><span class="p">(</span><span class="s2">"entries"</span><span class="p">,</span> <span class="s2">"entry"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">print</span> <span class="nb">map</span>
<span class="go">Route name Methods Path Controller action</span>
<span class="go">entries GET /entries{.format} entry index</span>
<span class="go">create_entry POST /entries{.format} entry create</span>
<span class="go">new_entry GET /entries/new{.format} entry new</span>
<span class="go">entry GET /entries/{id}{.format} entry show</span>
<span class="go">update_entry PUT /entries/{id}{.format} entry update</span>
<span class="go">delete_entry DELETE /entries/{id}{.format} entry delete</span>
<span class="go">edit_entry GET /entries/{id}/edit{.format} entry edit</span>
</pre></div>
</div>
<p><em>New in Routes 1.12.</em></p>
<p><em>Controller/action fields new in Routes 2.1</em></p>
</div>
<div class="section" id="introspection">
<h2>Introspection<a class="headerlink" href="#introspection" title="Permalink to this headline">¶</a></h2>
<p>The mapper attribute <code class="docutils literal notranslate"><span class="pre">.matchlist</span></code> contains the list of routes to be matched
against incoming URLs. You can iterate this list to see what routes are
defined. This can be useful when debugging route configurations.</p>
</div>
<div class="section" id="other">
<h2>Other<a class="headerlink" href="#other" title="Permalink to this headline">¶</a></h2>
<p>If your application is behind an HTTP proxy such a load balancer on another
host, the WSGI environment will refer to the internal server rather than to the
proxy, which will mess up generated URLs. Use the ProxyMiddleware in
PasteDeploy to fix the WSGI environment to what it would have been without the
proxy.</p>
<p>To debug routes, turn on debug logging for the “routes.middleware” logger.
(See Python’s <code class="docutils literal notranslate"><span class="pre">logging</span></code> module to set up your logging configuration.)</p>
</div>
<div class="section" id="backward-compatibility">
<h2>Backward compatibility<a class="headerlink" href="#backward-compatibility" title="Permalink to this headline">¶</a></h2>
<p>The following syntaxes are allowed for compatibility with previous versions
of Routes. They may be removed in the future.</p>
<div class="section" id="omitting-the-name-arg">
<h3>Omitting the name arg<a class="headerlink" href="#omitting-the-name-arg" title="Permalink to this headline">¶</a></h3>
<p>In the tutorial we said that nameless routes can be defined by passing <code class="docutils literal notranslate"><span class="pre">None</span></code>
as the first argument. You can also omit the first argument entirely:</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">"/</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="nb">map</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="p">)</span>
</pre></div>
</div>
<p>The syntax with <code class="docutils literal notranslate"><span class="pre">None</span></code> is preferred to be forward-compatible with future
versions of Routes. It avoids the path argument changing position between
the first and second arguments, which is unpythonic.</p>
</div>
<div class="section" id="varname">
<h3>:varname<a class="headerlink" href="#varname" title="Permalink to this headline">¶</a></h3>
<p>Path variables were defined in the format <code class="docutils literal notranslate"><span class="pre">:varname</span></code> and <code class="docutils literal notranslate"><span class="pre">:(varname)</span></code>
prior to Routes 1.9. The form with parentheses was called “grouping”, used
to delimit the variable name from a following letter or number. Thus the old
syntax “/:controller/:(id)abc” corresponds to the new syntax
“/{controller}/{id}abc”.</p>
<p>The older wildcard syntax is <code class="docutils literal notranslate"><span class="pre">*varname</span></code> or <code class="docutils literal notranslate"><span class="pre">*(varname)</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># OK because the following component is static.</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>
<span class="c1"># Deprecated syntax. WRONG because the wildcard will eat the rest of the</span>
<span class="c1"># URL, leaving nothing for the following variable, which will cause the</span>
<span class="c1"># match to fail.</span>
<span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">"/static/*filename/:action"</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="minimization">
<h3>Minimization<a class="headerlink" href="#minimization" title="Permalink to this headline">¶</a></h3>
<p>Minimization was a misfeature which was intended to save typing, but which
often resulted in the wrong route being chosen. Old applications that still
depend on it must now enable it by putting <code class="docutils literal notranslate"><span class="pre">map.minimization</span> <span class="pre">=</span> <span class="pre">True</span></code> in
their route definitions.</p>
<p>Without minimization, the URL must contain values for all path variables in
the 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">"basic"</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="n">controller</span><span class="o">=</span><span class="s2">"mycontroller"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"myaction"</span><span class="p">,</span> <span class="n">weather</span><span class="o">=</span><span class="s2">"sunny"</span><span class="p">)</span>
</pre></div>
</div>
<p>This route matches any two-component URL, for instance “/help/about”. The
resulting routing variables would be:</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">"help"</span><span class="p">,</span> <span class="s2">"action"</span><span class="p">:</span> <span class="s2">"about"</span><span class="p">,</span> <span class="s2">"weather"</span><span class="p">:</span> <span class="s2">"sunny"</span><span class="p">}</span>
</pre></div>
</div>
<p>The path variables are taken from the URL, and any extra variables are added as
constants. The extra variables for “controller” and “action” are <em>never used</em>
in matching, but are available as default values for generation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">url</span><span class="p">(</span><span class="s2">"basic"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s2">"help"</span><span class="p">)</span> <span class="o">=></span> <span class="s2">"/help/about?weather=sunny"</span>
</pre></div>
</div>
<p>With minimization, the same route path would also match shorter URLs such as
“/help”, “/foo”, and “/”. Missing values on the right of the URL would be
taken from the extra variables. This was intended to lessen the number of
routes you had to write. In practice it led to obscure application bugs
because sometimes an unexpected route would be matched. Thus Routes 1.9
introduced non-minimization and recommended “map.minimization = False” for
all new applications.</p>
<p>A corollary problem was generating the wrong route. Routes 1.9 tightened up
the rule for generating named routes. If a route name is specified in
<code class="docutils literal notranslate"><span class="pre">url()</span></code> or <code class="docutils literal notranslate"><span class="pre">url_for()</span></code>, <em>only</em> that named route will be chosen. In
previous versions, it might choose another route based on the keyword args.</p>
</div>
<div class="section" id="implicit-defaults-and-route-memory">
<h3>Implicit defaults and route memory<a class="headerlink" href="#implicit-defaults-and-route-memory" title="Permalink to this headline">¶</a></h3>
<p>Implicit defaults worked with minimization to provide automatic default values
for the “action” and “id” variables. If a route was defined as
<code class="docutils literal notranslate"><span class="pre">map.connect("/{controller}/{action}/{id}")</span> <span class="pre">and</span> <span class="pre">the</span> <span class="pre">URL</span> <span class="pre">"/archives"</span></code> was
requested, Routes would implicitly add <code class="docutils literal notranslate"><span class="pre">action="index",</span> <span class="pre">id=None</span></code> to the
routing variables.</p>
<p>To enable implicit defaults, set <code class="docutils literal notranslate"><span class="pre">map.minimization</span> <span class="pre">=</span> <span class="pre">True;</span> <span class="pre">map.explicit</span> <span class="pre">=</span>
<span class="pre">False</span></code>. You can also enable implicit defaults on a per-route basis by setting
<code class="docutils literal notranslate"><span class="pre">map.explicit</span> <span class="pre">=</span> <span class="pre">True</span></code> and defining each route with a keyword argument <code class="docutils literal notranslate"><span class="pre">explicit=False</span></code>.</p>
<p>Previous versions also had implicit default values for “controller”,
“action”, and “id”. These are now disabled by default, but can be enabled via
<code class="docutils literal notranslate"><span class="pre">map.explicit</span> <span class="pre">=</span> <span class="pre">True</span></code>. This also enables route memory</p>
</div>
<div class="section" id="url-for">
<h3>url_for()<a class="headerlink" href="#url-for" title="Permalink to this headline">¶</a></h3>
<p><code class="docutils literal notranslate"><span class="pre">url_for</span></code> was a route generation function which was replaced by the <code class="docutils literal notranslate"><span class="pre">url</span></code>
object. Usage is the same except that <code class="docutils literal notranslate"><span class="pre">url_for</span></code> uses route memory in some
cases and <code class="docutils literal notranslate"><span class="pre">url</span></code> never does. Route memory is where variables from the current
URL (the current request) are injected into the generated URL. To use route
memory with <code class="docutils literal notranslate"><span class="pre">url</span></code>, call <code class="docutils literal notranslate"><span class="pre">url.current()</span></code> passing the variables you want to
override. Any other variables needed by the route will be taken from the
current routing variables.</p>
<p>In other words, <code class="docutils literal notranslate"><span class="pre">url_for</span></code> combines <code class="docutils literal notranslate"><span class="pre">url</span></code> and <code class="docutils literal notranslate"><span class="pre">url.current()</span></code> into one
function. The location of <code class="docutils literal notranslate"><span class="pre">url_for</span></code> is also different. <code class="docutils literal notranslate"><span class="pre">url_for</span></code> is
properly imported from <code class="docutils literal notranslate"><span class="pre">routes</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">routes</span> <span class="k">import</span> <span class="n">url_for</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">url_for</span></code> was traditionally imported into WebHelpers, and it’s still used in
some tests and in <code class="docutils literal notranslate"><span class="pre">webhelpers.paginate</span></code>. Many old Pylons applications
contain <code class="docutils literal notranslate"><span class="pre">h.url_for()</span></code> based on its traditional importation to helpers.py.
However, its use in new applications is discouraged both because of its
ambiguous syntax and because its implementation depends on an ugly singleton.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">url</span></code> object is created by the RoutesMiddleware and inserted into the
WSGI environment. Pylons makes it available as <code class="docutils literal notranslate"><span class="pre">pylons.url</span></code>, and in
templates as <code class="docutils literal notranslate"><span class="pre">url</span></code>.</p>
</div>
<div class="section" id="redirect-to">
<h3>redirect_to()<a class="headerlink" href="#redirect-to" title="Permalink to this headline">¶</a></h3>
<p>This combined <code class="docutils literal notranslate"><span class="pre">url_for</span></code> with a redirect. Instead, please use your
framework’s redirect mechanism with a <code class="docutils literal notranslate"><span class="pre">url</span></code> call. For instance in Pylons:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">pylons.controllers.util</span> <span class="k">import</span> <span class="n">redirect</span>
<span class="n">redirect</span><span class="p">(</span><span class="n">url</span><span class="p">(</span><span class="s2">"login"</span><span class="p">))</span>
</pre></div>
</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="#">Unicode, Redirects, and More</a><ul>
<li><a class="reference internal" href="#unicode">Unicode</a></li>
<li><a class="reference internal" href="#redirect-routes">Redirect Routes</a></li>
<li><a class="reference internal" href="#printing">Printing</a></li>
<li><a class="reference internal" href="#introspection">Introspection</a></li>
<li><a class="reference internal" href="#other">Other</a></li>
<li><a class="reference internal" href="#backward-compatibility">Backward compatibility</a><ul>
<li><a class="reference internal" href="#omitting-the-name-arg">Omitting the name arg</a></li>
<li><a class="reference internal" href="#varname">:varname</a></li>
<li><a class="reference internal" href="#minimization">Minimization</a></li>
<li><a class="reference internal" href="#implicit-defaults-and-route-memory">Implicit defaults and route memory</a></li>
<li><a class="reference internal" href="#url-for">url_for()</a></li>
<li><a class="reference internal" href="#redirect-to">redirect_to()</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="restful.html"
title="previous chapter">RESTful services</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="changes.html"
title="next chapter">Routes Changelog</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/uni_redirect_rest.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="changes.html" title="Routes Changelog"
>next</a> |</li>
<li class="right" >
<a href="restful.html" title="RESTful services"
>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
>
96
