1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
|
<!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="Content-Type" content="text/html; charset=utf-8" />
<title>Setting up routes — Routes v1.12.3 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '#',
VERSION: '1.12.3',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Routes v1.12.3 documentation"
href="_static/opensearch.xml"/>
<link rel="top" title="Routes v1.12.3 documentation" href="index.html" />
<link rel="next" title="Generation" href="generating.html" />
<link rel="prev" title="Introduction" href="introduction.html" />
</head>
<body>
<div style="color: #D1361B; font-size: 70px; font-weight: bold; padding: 10px 0 0 10px;">Routes</div>
</div>
<div class="related">
<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="modindex.html" title="Global Module Index"
accesskey="M">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><a href="index.html">Routes home</a> | </li>
<li><a href="contents.html">Documentation</a>»</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<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 <tt class="docutils literal"><span class="pre">make_map</span></tt> function in your
<em>myapp/config/routing.py</em> module. Here is a typical configuration:</p>
<div class="highlight-python"><pre>1 from routes import Mapper
2 map = Mapper()
3 map.connect(None, "/error/{action}/{id}, controller="error")
4 map.connect("home", "/", controller="main", action="index")
5 # ADD CUSTOM ROUTES HERE
6 map.connect(None, "/{controller}/{action}")
7 map.connect(None, "/{controller}/{action}/{id}")</pre>
</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-python"><div class="highlight"><pre><span class="p">{</span><span class="s">"controller"</span><span class="p">:</span> <span class="s">"error"</span><span class="p">,</span> <span class="s">"action"</span><span class="p">:</span> <span class="s">"images"</span><span class="p">,</span> <span class="s">"id"</span><span class="p">:</span> <span class="s">"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 <tt class="xref docutils literal"><span class="pre">None</span></tt> 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-python"><div class="highlight"><pre><span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s">"/feeds/{category}/atom.xml"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s">"feeds"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"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="s">"history"</span><span class="p">,</span> <span class="s">"/archives/by_eon/{century}"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s">"archives"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s">"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="s">"article"</span><span class="p">,</span> <span class="s">"/article/{section}/{slug}/{page}.html"</span><span class="p">,</span>
<span class="n">controller</span><span class="o">=</span><span class="s">"article"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"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, <tt class="docutils literal"><span class="pre">str()</span></tt> 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 <tt class="docutils literal"><span class="pre">Backward</span> <span class="pre">Compatibility</span></tt> 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 <tt class="docutils literal"><span class="pre">requirements</span></tt> argument. An inline
requirement looks like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s">R"/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="s">R"/download/{platform:windows|mac}/{filename}"</span><span class="p">)</span>
</pre></div>
</div>
<p>This matches “/blog/123” but not “/blog/12A”. The equivalent <tt class="docutils literal"><span class="pre">requirements</span></tt>
syntax is:</p>
<div class="highlight-python"><pre>map.connect("/blog/{id}", requirements={"id": R"\d+"}
map.connect("/download/{platform}/{filename}",
requirements={"platform": R"windows|mac"})</pre>
</div>
<p>Note the use of raw string syntax (<tt class="docutils literal"><span class="pre">R""</span></tt>) for regexes which might contain
backslashes. Without the R you’d have to double every backslash.</p>
<p>Another example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s">"archives/{year}/{month}/{day}"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s">"archives"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s">"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="s">R"\d{2,4}"</span><span class="p">,</span> <span class="n">month</span><span class="o">=</span><span class="s">R"\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 <tt class="docutils literal"><span class="pre">requirements</span></tt> argument. Two advantages of the
<tt class="docutils literal"><span class="pre">requirements</span></tt> 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-python"><div class="highlight"><pre><span class="n">NUMERIC</span> <span class="o">=</span> <span class="s">R"\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="s">"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="s">"year"</span><span class="p">:</span> <span class="s">R"\d\d\d\d"</span><span class="p">,</span> <span class="s">"month"</span><span class="p">:</span> <span class="s">R"\d\d"</span><span class="p">,</span> <span class="s">"day"</span><span class="p">:</span> <span class="s">R"\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 <tt class="docutils literal"><span class="pre">requirements</span></tt> 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-python"><pre>map.connect(None, "/cards/{path_info:.*}",
controller="main", action="cards")
# Incoming URL "/cards/diamonds/4.png"
=> {"controller": "main", action: "cards", "path_info": "/diamonds/4.png"}
# Second WSGI application sees:
# SCRIPT_NAME="/cards" PATH_INFO="/diamonds/4.png"</pre>
</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-python"><div class="highlight"><pre><span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s">"cards"</span><span class="p">,</span> <span class="s">"/cards"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s">"main"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"cards"</span><span class="p">,</span>
<span class="n">path_info</span><span class="o">=</span><span class="s">"/"</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-python"><div class="highlight"><pre><span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s">"cards"</span><span class="p">,</span> <span class="s">"/cards{path_info:.*}"</span><span class="p">,</span>
<span class="n">controller</span><span class="o">=</span><span class="s">"main"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"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-python"><div class="highlight"><pre><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="s">"/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 <tt class="docutils literal"><span class="pre">__controller__</span></tt> variable set to
the WSGI application:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">"/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 <tt class="docutils literal"><span class="pre">conditions</span></tt> argument is a dict with up to three keys:</p>
<blockquote>
<p>method</p>
<blockquote>
A list of uppercase HTTP methods. The request must be one of the
listed methods.</blockquote>
<p>sub_domain</p>
<blockquote>
<p>Can be a list of subdomains, <tt class="xref docutils literal"><span class="pre">True</span></tt>, <tt class="xref docutils literal"><span class="pre">False</span></tt>, or <tt class="xref docutils literal"><span class="pre">None</span></tt>. If a
list, the request must be for one of the specified subdomains. If
<tt class="xref docutils literal"><span class="pre">True</span></tt>, the request must contain a subdomain but it can be anything.
If <tt class="xref docutils literal"><span class="pre">False</span></tt> or <tt class="xref docutils literal"><span class="pre">None</span></tt>, do not match if there’s a subdomain.</p>
<p><em>New in Routes 1.10: ``False`` and ``None`` values.</em></p>
</blockquote>
<p>function</p>
<blockquote>
A function that evaluates the request. Its signature must be
<tt class="docutils literal"><span class="pre">func(environ,</span> <span class="pre">match_dict)</span> <span class="pre">=></span> <span class="pre">bool</span></tt>. 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 <tt class="docutils literal"><span class="pre">match_dict</span></tt>
in place to affect which variables are returned. This allows a wide
range of transformations.</blockquote>
</blockquote>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># 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="s">"/user/list"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s">"user"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"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="s">"GET"</span><span class="p">,</span> <span class="s">"HEAD"</span><span class="p">]))</span>
<span class="c"># 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="s">"/"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s">"user"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"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="bp">True</span><span class="p">))</span>
<span class="c"># 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="s">"/"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s">"user"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"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="s">"fred"</span><span class="p">,</span> <span class="s">"george"</span><span class="p">]))</span>
<span class="c"># Put the referrer into the resulting match dictionary.</span>
<span class="c"># This function always returns true, so it never prevents the match</span>
<span class="c"># 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="s">"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="s">"HTTP_REFERER"</span><span class="p">)</span>
<span class="k">return</span> <span class="bp">True</span>
<span class="n">m</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s">"/{controller}/{action}/{id}"</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-python"><div class="highlight"><pre><span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s">"/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-python"><div class="highlight"><pre><span class="c"># 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="s">"/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 <tt class="docutils literal"><span class="pre">{.format}</span></tt> 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 <tt class="xref docutils literal"><span class="pre">None</span></tt> otherwise. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s">'/entries/{id}{.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-python"><div class="highlight"><pre><span class="nb">map</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s">'/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 <tt class="docutils literal"><span class="pre">\d+</span></tt> requirement on the <tt class="docutils literal"><span class="pre">id</span></tt> variable above, “/entries/1.mp3” would match
successfully, with the <tt class="docutils literal"><span class="pre">id</span></tt> 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 <tt class="docutils literal"><span class="pre">with</span></tt> block, and the other avoiding it.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># 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="s">"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="s">"home"</span><span class="p">,</span> <span class="s">"/"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"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="s">"index"</span><span class="p">,</span> <span class="s">"/index"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"index"</span><span class="p">)</span>
<span class="c"># 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="s">"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="s">"home"</span><span class="p">,</span> <span class="s">"/"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"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="s">"index"</span><span class="p">,</span> <span class="s">"/index"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"index"</span><span class="p">)</span>
<span class="c"># Both of these syntaxes create the following routes::</span>
<span class="c"># "/" => {"controller": "home", action="splash"}</span>
<span class="c"># "/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-python"><div class="highlight"><pre><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="s">"/admin"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s">"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="s">"admin_users"</span><span class="p">,</span> <span class="s">"/users"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"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="s">"admin_databases"</span><span class="p">,</span> <span class="s">"/databases"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"databases"</span><span class="p">)</span>
<span class="c"># /admin/users => {"controller": "admin", "action": "users"}</span>
<span class="c"># /admin/databases => {"controller": "admin", "action": "databases"}</span>
</pre></div>
</div>
<p>All arguments to <tt class="docutils literal"><span class="pre">.submapper</span></tt> must be keyword arguments.</p>
<p>The submapper is <em>not</em> a complete mapper. It’s just a temporary object
with a <tt class="docutils literal"><span class="pre">.connect</span></tt> 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-python"><div class="highlight"><pre><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="s">"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="s">"home"</span><span class="p">,</span> <span class="s">"/"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"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="s">"index"</span><span class="p">,</span> <span class="s">"/index"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"index"</span><span class="p">)</span>
</pre></div>
</div>
<p>can be written:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">"home"</span><span class="p">,</span> <span class="n">path_prefix</span><span class="o">=</span><span class="s">"/"</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="s">"home"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"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="s">"index"</span><span class="p">)</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">action</span></tt> helper generates a route for one or more HTTP methods (‘GET’ is
assumed) at the submapper’s path (‘/’ in the example above). The <tt class="docutils literal"><span class="pre">link</span></tt>
helper generates a route at a relative path.</p>
<p>There are specific helpers corresponding to the standard <tt class="docutils literal"><span class="pre">index</span></tt>, <tt class="docutils literal"><span class="pre">new</span></tt>,
<tt class="docutils literal"><span class="pre">create</span></tt>, <tt class="docutils literal"><span class="pre">show</span></tt>, <tt class="docutils literal"><span class="pre">edit</span></tt>, <tt class="docutils literal"><span class="pre">update</span></tt> and <tt class="docutils literal"><span class="pre">delete</span></tt> actions.
You can use these directly:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">"entries"</span><span class="p">,</span> <span class="n">path_prefix</span><span class="o">=</span><span class="s">"/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="s">"/{id}"</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-python"><div class="highlight"><pre><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="s">"entries"</span><span class="p">,</span> <span class="n">path_prefix</span><span class="o">=</span><span class="s">"/entries"</span><span class="p">,</span>
<span class="n">actions</span><span class="o">=</span><span class="p">[</span><span class="s">"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="s">"/{id}"</span><span class="p">,</span> <span class="n">actions</span><span class="o">=</span><span class="p">[</span><span class="s">"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-python"><div class="highlight"><pre><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="s">"entries"</span><span class="p">,</span> <span class="n">member_name</span><span class="o">=</span><span class="s">"entry"</span><span class="p">,</span>
<span class="n">controller</span><span class="o">=</span><span class="s">"entries"</span><span class="p">,</span>
<span class="n">collection_actions</span><span class="o">=</span><span class="p">[</span><span class="s">"index"</span><span class="p">],</span> <span class="n">member_actions</span><span class="p">[</span><span class="s">"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 <tt class="docutils literal"><span class="pre">member</span></tt> property (a nested submapper) to which which member-specific routes
can be added. When <tt class="docutils literal"><span class="pre">collection_actions</span></tt> or <tt class="docutils literal"><span class="pre">member_actions</span></tt> are omitted,
the full set of actions is generated (see the example under “Printing” below).</p>
<p>See “RESTful services” below for <tt class="docutils literal"><span class="pre">map.resource</span></tt>, a precursor to
<tt class="docutils literal"><span class="pre">map.collection</span></tt> 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 <tt class="docutils literal"><span class="pre">.extend</span></tt> method, optionally providing a path prefix:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">routes</span> <span class="o">=</span> <span class="p">[</span>
<span class="n">Route</span><span class="p">(</span><span class="s">"index"</span><span class="p">,</span> <span class="s">"/index.html"</span><span class="p">,</span> <span class="n">controller</span><span class="o">=</span><span class="s">"home"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"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="c"># /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="s">"/subapp"</span><span class="p">)</span>
<span class="c"># /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">
<div class="sphinxsidebarwrapper">
<h3><a href="contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference external" href="#">Setting up routes</a><ul>
<li><a class="reference external" href="#requirements">Requirements</a></li>
<li><a class="reference external" href="#magic-path-info">Magic path_info</a></li>
<li><a class="reference external" href="#conditions">Conditions</a></li>
<li><a class="reference external" href="#wildcard-routes">Wildcard routes</a></li>
<li><a class="reference external" href="#format-extensions">Format extensions</a></li>
<li><a class="reference external" href="#submappers">Submappers</a></li>
<li><a class="reference external" href="#submapper-helpers">Submapper helpers</a></li>
<li><a class="reference external" 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>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/setting_up.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<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="modindex.html" title="Global 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><a href="index.html">Routes home</a> | </li>
<li><a href="contents.html">Documentation</a>»</li>
</ul>
</div>
<div class="footer">
© Copyright 2010, Ben Bangert, Mike Orr.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.5.
</div>
</body>
</html>
|
