diff options
| -rw-r--r-- | .hgignore | 1 | ||||
| -rw-r--r-- | docs/index.rst | 2 | ||||
| -rw-r--r-- | docs/manual.rst | 901 |
3 files changed, 904 insertions, 0 deletions
@@ -7,3 +7,4 @@ syntax:glob *.egg build dist +docs/_build diff --git a/docs/index.rst b/docs/index.rst index a08e3cc..588721e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,6 +10,8 @@ Contents: .. toctree:: :maxdepth: 2 + manual + Indices and tables ================== diff --git a/docs/manual.rst b/docs/manual.rst new file mode 100644 index 0000000..04e437e --- /dev/null +++ b/docs/manual.rst @@ -0,0 +1,901 @@ +Routes Manual +%%%%%%%%%%%%% + +*Updated 2009-03-30* + +Introduction +============ + +Routes tackles an interesting problem that comes up frequently in web +development, *how do you map URLs to your application's actions*? That is, how +do you say that *this* should be accessed as "/blog/2008/01/08", and "/login" +should do *that*? Many web frameworks have a fixed dispatching system; e.g., +"/A/B/C" means to read file "C" in directory "B", or to call method "C" of +class "B" in module "A.B". These work fine until you need to refactor your code +and realize that moving a method changes its public URL and invalidates users' +bookmarks. Likewise, if you want to reorganize your URLs and make a section +into a subsection, you have to change your carefully-tested logic code. + +Routes takes a different approach. You determine your URL hierarchy and and +actions separately, and then link them together in whichever ways you decide. +If you change your mind about a particular URL, just change one line in your +route map and never touch your action logic. You can even have multiple URLs +pointing to the same action; e.g., to support legacy bookmarks. Routes was +originally inspired by the dispatcher in Ruby on Rails but has since diverged. + +Routes is the primary dispatching system in the Pylons web framework, and an +optional choice in CherryPy. It can be added to any +framework without much fuss, and used for an entire site or a URL subtree. +It can also forward subtrees to other dispatching systems, which is how +TurboGears 2 is implemented on top of Pylons. + +.. + Routes 2 is a rewrite which makes Routes simpler and more deterministic, + following the Python slogan "Explicit is better than implicit". + +Most of this manual is written from the user's perspective: how to use Routes in a framework that already supports it. The last section shows how to add Routes support to a new framework. + +Current features: + +* Sophisticated route lookup and URL generation +* Named routes +* Redirect routes +* Wildcard paths before and after static parts +* Sub-domain support built-in +* Conditional matching based on domain, cookies, HTTP method (RESTful), and more +* Easily extensible utilizing custom condition functions and route generation + functions +* Extensive unit tests + + + + +Buzzword compliance: REST, DRY. + +A rewrite of Routes called "Routes 2" is in progress but no release date has +been set. Many of Routes 2's features have been backported to Routes 1, making +the future of Routes 2 less certain. + +Vocabulary +========== + +A **route** is a rule for mapping a URL pattern to a dict of **routing +variables**. For instance, if the pattern is "/{controller}/{action}" and the +requested URL is "/help/about", Routes would return:: + + {"controller": "help", "action": "about"}`` + +What the application does with these variables is none of Routes' business, but +Pylons would look for a ``HelpController`` class and call its ``about`` method. + +A **mapper** is an object that holds a collection of routes and can match and +generate them. **Matching** is the act of finding a corresponding route for a +given URL and returning routing variables. **Generation** is the opposite, +creating a URL based on a route name and variable values. + +The URL pattern is called the **route path**, and variables defined in it are +**path variables**. Variables defined outside the path (which we'll see later) +are called **extra variables** or **default variables**. + +The routing variables returned by the matcher are thus a combination of path +variables and extra variables. wsgi.org confusingly calls routing variables +"routing args". This manual avoids the term because it can be confused with +extra variables, which are defined via keyword arguments. + + +Setting up routes +================= + +It is assumed that you are using a framework that has preconfigured Routes for +you. In Pylons, you define your routes in the ``make_map`` function in your +*myapp/config/routing.py* module. Here is a typical configuration:: + + 1 from routes import Mapper + 2 map = Mapper() + 3 map.minimization = False + 4 map.connect("/error/{action}/{id}, controller="error") + 5 map.connect("home", "/", controller="main", action="index") + 6 # ADD CUSTOM ROUTES HERE + 7 map.connect("/{controller}/{action}") + 8 map.connect("/{controller}/{action}/{id}") + +The last two routes (lines 7 and 8) should be familiar from the example above. +They match any two-component or three-component URL. + +Line 4 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:: + + {"controller": "error", "action": "images", "id": "arrow.jpg"} + +Line 5 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. +Note that the route path moves from the first argument to the second if the +route has a name. Routes with a name are called **named routes**; those +without are called **nameless routes**. It's recommended to name all routes +that may be used for generation. + +Note that a URL "/error/images/arrow.jpg" could match both line 4 and line 8. +The mapper resolves this by trying routes in the order defined, so this URL +would match line 4. + +Line 3 is a backward compatibility option which you should set to false. +Minimization allowed a route to match if some rightmost components are missing +and default values are supplied in the route definition. With minimization, +line 8 could match "/mycontroller/myaction", "/mycontroller", or even "/" if +the missing variables were specified in the route definition, so line 7 would +not be necessary. In practice, minimization led to application bugs when an +unintended route matched, so it is no longer recommended. Without +minimization, you just have to add additional routes to match the shorter URLs. + +If no routes match the URL, the mapper returns a "match failed" condition, +which is seen in Pylons as HTTP 404 "Not Found". + +Here are some more examples of valid routes:: + + m.connect("/feeds/{category}/atom.xml", controller="feeds", action="atom") + m.connect("history", "/archives/by_eon/{century}", controller="archives", + action="aggregate") + m.connect("article", "/article/{section}/{slug}/{page}.html", + controller="article", action="view") + +Extra variables may be any Python type, not just strings. However, if the +route is used in generation, ``str()`` will be called on the value unless +the generation call specifies an overriding value. + +.. tip:: Version differences + + The ``{varname}`` syntax for path variables was introduced in Routes 1.9 + for forward compatibility with Routes 2. Earlier versions used + ``:varname`` and ``:(varname)``. The older syntax is still supported but + deprecated. + + Previous versions would match a URL beginning with a slash ("/") even if + the route was defined without it. This is no longer + supported, so always define your URL patterns with an initial slash. + + Previous versions also had implicit default values for "controller", + "action", and "id". These are now disabled by default. + + Non-minimization was also introduced in Routes 1.9. + + + +Requirements +------------ + +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 ``requirements`` argument. An inline +requirement looks like this:: + + map.connect(R"/blog/{id:\d+}") + map.connect(R"/download/{platform:windows|mac}/{filename}") + +This matches "/blog/123" but not "/blog/12A". The equivalent ``requirements`` +syntax is:: + + map.connect("/blog/{id}", requirements={"id": R"\d+"} + map.connect("/download/{platform}/{filename}", + requirements={"platform": R"windows|mac"}) + +Note the use of raw string syntax (``R""``) for regexes which might contain +backslashes. Without the R you'd have to double every backslash. + +Another example:: + + m.connect("archives/{year}/{month}/{day}", controller="archives", + action="view", year=2004, + requirements=dict(year=R"\d{2,4}", month=R"\d{1,2}")) + +The inline syntax was added in Routes (XXX 1.10?? not in changelog). Previous +versions had only the ``requirements`` argument. Two advantages of the +``requirements`` argument are that if you have several variables with identical +requirements, you can set one variable or even the entire argument to a +global:: + + NUMERIC = R"\d+" + map.connect(..., requirements={"id": NUMERIC}) + + ARTICLE_REQS = {"year": R"\d\d\d\d", "month": R"\d\d", "day": R"\d\d"} + map.connect(..., requirements=ARTICLE_REQS) + +Because the argument ``requirements`` is reserved, you can't define a routing +variable by that name. + +Magic path_info +--------------- + +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. :: + + map.connect("cards", "/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" + +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:: + + from paste.fileapp import DirectoryApp + def cards(self, environ, start_response): + app = DirectoryApp("/cards-directory") + return app(environ, start_response) + +Or create a fake controller module with a ``__controller__`` variable set to +the WSGI application:: + + import paste.fileapp + __controller__ = DirectoryApp("/cards-directory") + +Conditions +---------- + +Conditions impose additional constraints on what kinds of requests can match. +The ``conditions`` argument is a dict with up to three keys: + + method + + A list of uppercase HTTP methods. The request must be one of the + listed methods. + + sub_domain + + Can be a list of subdomains, ``True``, ``False``, or ``None``. If a + list, the request must be for one of the specified subdomains. If + ``True``, the request must contain a subdomain but it can be anything. + If ``False`` or ``None``, do not match if there's a subdomain. + + (New in Routes 1.10: ``False`` and ``None`` values.) + + function + + A function that evaluates the request. Its signature must be + ``func(environ, match_dict) => bool``. 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 ``match_dict`` + in place to affect which variables are returned. This allows a wide + range of transformations. + +Examples:: + + # Match only if the HTTP method is "GET" or "HEAD". + m.connect("/user/list", controller="user", action="list", + conditions=dict(method=["GET", "HEAD"])) + + # A sub-domain should be present. + m.connect("/", controller="user", action="home", + conditions=dict(sub_domain=True)) + + # Sub-domain should be either "fred" or "george". + m.connect("/", controller="user", action="home", + conditions=dict(sub_domain=["fred", "george"])) + + # Put the referrer into the resulting match dictionary. + # This function always returns true, so it never prevents the match + # from succeeding. + def referals(environ, result): + result["referer"] = environ.get("HTTP_REFERER") + return True + m.connect("/{controller}/{action}/{id}", + conditions=dict(function=referals)) + +Wildcard routes +--------------- + +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:: + + map.connect("/static/{filename:.*?}") + +This matches "/static/foo.jpg", "/static/bar/foo.jpg", etc. + +Older versions of Routes had a different syntax for wildcard routes: +``*varname`` or ``*(varname)``. This syntax is still supported but deprecated. + +Beware that careless regexes may eat the entire rest of the URL and cause +components to the right of it not to match:: + + # OK because the following component is static and the regex has a "?". + map.connect("/static/{filename:.*?}/download") + + # Deprecated syntax. OK because the following component is static. + map.connect("/static/*filename/download") + + # Deprecated syntax. WRONG because the wildcard will eat the rest of the + # URL, leaving nothing for the following variable, which will cause the + # match to fail. + map.connect("/static/*filename/:action") + +The lesson is to always test wildcard patterns. + + +Generation +========== + +To generate URLs, use the ``url`` or ``url_for`` object provided by your +framework. ``url`` is an instance of Routes ``URLGenerator``, while +``url_for`` is the older ``routes.url_for()`` function. + +To generate a named route, specify the route name as a positional argument:: + + url("home") => "/" + +If the route contains path variables, you must specify values for them using +keyword arguments:: + + url("blog", year=2008, month=10, day=2) + +Non-string values are automatically converted to strings using ``str()``. +(This may break with Unicode values containing non-ASCII characters.) + +However, if the route defines an extra variable with the same name as a path +variable, the extra variable is used as the default if that keyword is not +specified. Example:: + + m.connect("archives", "/archives/{id}", + controller="archives", action="view", id=1) + url("blog", id=123) => "/blog/123" + url("blog") => "/blog/1" + +(The extra variable is *not* used for matching unless minimization is enabled.) + +Any keyword args that do not correspond to path variables will be put in the +query string. Append a "_" if the variable name collides with a Python +keyword:: + + map.connect("archive", "/archive/{year}") + url("archive", year=2009, font=large) => "/archive/2009?font=large" + url("archive", year=2009, print_=1) => "/archive/2009?print=1" + +If the application is mounted at a subdirectory of the URL space, +all generated URLs will have the application prefix. The application prefix is +the "SCRIPT_NAME" variable in the request's WSGI environment. + +If the positional argument corresponds to no named route, it is assumed to be a +literal URL. The application's mount point is prefixed to it, and keyword args +are converted to query parameters:: + + url("/search", q="My question") => "/search?q=My+question" + +If there is no positional argument, Routes will use the keyword args to choose +a route. The first route that has all path variables specified by keyword args +and the fewest number of extra variables not overridden by keyword args will be +chosen. This was common in older versions of Routes but can cause application +bugs if an unexpected route is chosen, so using route names is much preferable +because that guarantees only the named route will be chosen. The most common +use for unnamed generation is when you have a seldom-used controller with a lot +of ad hoc methods; e.g., ``url(controller="admin", action="session")``. + +An exception is raised if no route corresponds to the arguments. The exception +is ``routes.util.GenerationException``. (Prior to Routes 1.9, ``None`` was +returned instead. It was changed to an exception to prevent invalid blank URLs +from being insered into templates.) + +You'll also get this exception if Python produces a Unicode URL (which could +happen if the route path or a variable value is Unicode). Routes generates +only ``str`` URLs. + +The following keyword args are special: + + anchor + + Specifies the URL anchor (the part to the right of "#"). :: + + url("home", "summary") => "/#summary" + + host + + Make the URL fully qualified and override the host (domain). + + protocol + + Make the URL fully qualified and override the protocol (e.g., "ftp"). + + qualified + + Make the URL fully qualified (i.e., add "protocol://host:port" prefix). + + sub_domain + + See "Generating URLs with subdomains" below. + +The syntax in this section is the same for both ``url`` and ``url_for``. + +Generating routes based on the current URL +------------------------------------------ + +``url.current()`` returns the URL of the current request, without the query +string. This is called "route memory", and works only if the RoutesMiddleware +is in the middleware stack. Keyword arguments override path variables or are +put on the query string. + +``url_for`` combines the behavior of ``url`` and ``url_current``. This is +deprecated because nameless routes and route memory have the same syntax, which +can lead to the wrong route being chosen in some cases. + +Here's an example of route memory:: + + # Deprecated route memory example. + m.connect("/archives/{year}/{month}/{day}", year=2004) + + # Current URL is "/archives/2005/10/4". + # Routing variables are {"controller": "archive", "action": "view", + "year": "2005", "month": "10", "day": "4"} + + url_for(day=6) => "/archives/2005/10/6" + url_for(month=4) => "/archives/2005/4/4" + url_for() => "/archives/2005/10/4" + +Route memory can be disabled globally with ``map.explicit = True``. + +Generation-only routes (aka. static routes) +------------------------------------------- + +A static route is used only for generation -- not matching -- and it must be +named. To define a static route, use the argument ``_static=True``. + +This example provides a convenient way to link to a search:: + + map.connect("google", "http://google.com/", _static=True) + url("google", q="search term") => "/http://google.com/?q=search+term") + +This example generates a URL to a static image in a Pylons public directory. +Pylons serves the public directory in a way that bypasses Routes, so there's no +reason to match URLs under it. :: + + map.connect("attachment", "/images/attachments/{category}/{id}.jpg", + _static=True) + url("attachment", category="dogs", id="Mastiff") => + "/images/attachments/dogs/Mastiff.jpg" + +In Routes 1.10 and later, static routes are exactly the same as regular routes +except they're not added to the internal match table. In older versions of +Routes they could not contain path variables and they had to point to external +URLs. These restrictions no longer apply. + +Filter functions +---------------- + +A filter function modifies how a named route is generated. Don't confuse it +with a function condition, which is used in matching. A filter function is its +opposite counterpart. + +One use case is when you have a ``story`` object with attributes for year, +month, and day. You don't want to hardcode these attributes in every ``url`` +call because the interface may change someday. Instead you pass the story as a +pseudo-argument, and the filter produces the actual generation args. Here's an +example:: + + class Story(object): + def __init__(self, year, month, day): + self.year = year + self.month = month + self.day = day + + @staticmethod + def expand(kw): + try: + story = kw["story"] + except KeyError: + pass # Don't modify dict if ``story`` key not present. + else: + # Set the actual generation args from the story. + kw["year"] = story.year + kw["month"] = story.month + kw["day"] = story.day + return kw + + m.connect("archives", "/archives/{year}/{month}/{day}", + controller="archives", action="view", _filter=Story.expand) + + my_story = Story(2009, 1, 2) + url("archives", story=my_story) => "/archives/2009/1/2" + +The ``_filter`` argument can be any function that takes a dict and returns a +dict. In the example we've used a static method of the ``Story`` class to keep +everything story-related together, but you may prefer to use a standalone +function to keep Routes-related code away from your model. + +Generating URLs with subdomains +------------------------------- + +If subdomain support is enabled and the ``sub_domain`` arg is passed to +``url_for``, Routes ensures the generated route points to that subdomain. :: + + # Enable subdomain support. + map.sub_domains = True + + # Ignore the www subdomain. + map.sub_domains_ignore = "www" + + map.connect("/users/{action}") + + # Add a subdomain. + url_for(action="update", sub_domain="fred") => "http://fred.example.com/users/update" + + # Delete a subdomain. Assume current URL is fred.example.com. + url_for(action="new", sub_domain=None) => "http://example.com/users/new" + +Unicode +======= + +Routes assumes UTF-8 encoding on incoming URLs, and ``url`` and ``url_for`` +also generate UTF-8. You can change the encoding with the ``map.charset`` +attribute:: + + map.charset = "latin-1" + +New in Routes 1.10: several bugfixes. + +RESTful services +================ + +Routes makes it easy to configure RESTful web services. ``map.resource`` +creates a set of add/modify/delete routes conforming to the Atom publishing +protocol. + +A resource route addresses *members* in a *collection*, and the collection +itself. Normally a collection is a plural word, and a member is the +corresponding singular word. For instance, consider a collection of messages:: + + map.resource("message", "messages") + + # The above command sets up several routes as if you had typed the + # following commands: + map.connect("messages", "/messages", + controller="messages", action="create", + conditions=dict(method=["POST"])) + map.connect("messages", "/messages", + controller="messages", action="index", + conditions=dict(method=["GET"])) + map.connect("formatted_messages", "/messages.{format}", + controller="messages", action="index", + conditions=dict(method=["GET"])) + map.connect("new_message", "/messages/new", + controller="messages", action="new", + conditions=dict(method=["GET"])) + map.connect("formatted_new_message", "/messages/new.{format}", + controller="messages", action="new", + conditions=dict(method=["GET"])) + map.connect("/messages/{id}", + controller="messages", action="update", + conditions=dict(method=["PUT"])) + map.connect("/messages/{id}", + controller="messages", action="delete", + conditions=dict(method=["DELETE"])) + map.connect("edit_message", "/messages/{id}/edit", + controller="messages, action="edit", + conditions=dict(method=[""GET"])) + map.connect("formatted_edit_message", "/messages/{id}.{format}/edit", + controller="messages, action="edit", + conditions=dict(method=[""GET"])) + map.connect("message", "/messages/{id}", + controller="messages", action="show", + conditions=dict(method=["GET"])) + map.connect("formatted_message", "/messages/{id}.{format}", + controller="messages", action="show", + conditions=dict(method=["GET"])) + +This establishes the following convention:: + + GET /messages => messages.index() => url("messages") + POST /messages => messages.create() => url("messages") + GET /messages/new => messages.new() => url("new_message") + PUT /messages/1 => messages.update(id) => url("message", id=1) + DELETE /messages/1 => messages.delete(id) => url("message", id=1) + GET /messages/1 => messages.show(id) => url("message", id=1) + GET /messages/1/edit => messages.edit(id) => url("edit_message", id=1) + +Thus, you GET the collection to see an index of links to members ("index" +method). You GET a member to see it ("show"). You GET "COLLECTION/new" to +obtain a new message form ("new"), which you POST to the collection ("create"). +You GET "MEMBER/edit" to obtain an edit for ("edit"), which you PUT to the +member ("update"). You DELETE the member to delete it. Note that there are +only four route names because multiple actions are doubled up on the same URLs. + +This URL structure may look strange if you're not used to the Atom protocol. +REST is a vague term, and some people think it means proper URL syntax (every +component contains the one on its right), others think it means not putting IDs +in query parameters, and others think it means using HTTP methods beyond GET +and POST. ``map.resource`` does all three, but it may be overkill for +applications that don't need Atom compliance or prefer to stick with GET and +POST. ``map.resource`` has the advantage that many automated tools and +non-browser agents will be able to list and modify your resources without any +programming on your part. But you don't have to use it if you prefer a simpler +add/modify/delete structure. + +HTML forms can produce only GET and POST requests. As a workaround, if a POST +request contains a ``_method`` parameter, the Routes middleware changes the +HTTP method to whatever the parameter specifies, as if it had been requested +that way in the first place. This convention is becoming increasingly common +in other frameworks. If you're using WebHelpers, the The WebHelpers ``form`` +function has a ``method`` argument which automatically sets the HTTP method and +"_method" parameter. + +Several routes are paired with an identical route containing the ``format`` +variable. The intention is to allow users to obtain different formats by means +of filename suffixes; e.g., "/messages/1.xml". This produces a routing +variable "xml", which in Pylons will be passed to the controller action if it +defines a formal argument for it. In generation you can pass the ``format`` +argument to produce a URL with that suffix:: + + url("message", id=1, format="xml") => "/messages/1.xml" + +Routes does not recognize any particular formats or know which ones are valid +for your application. It merely passes the ``format`` attribute through if it +appears. + +New in Routes 1.7.3: changed URL suffix from ";edit" to "/edit". Semicolons +are not allowed in the path portion of a URL except to delimit path parameters, +which nobody uses. + +Resource options +---------------- + +The ``map.resource`` method recognizes a number of keyword args which modifies +its behavior: + +controller + + Use the specified controller rather than deducing it from the collection + name. + +collection + + Additional URLs to allow for the collection. Example:: + + map.resource("message", "messages", collection={"rss": "GET"}) + # "GET /message/rss" => ``Messages.rss()``. + # Defines a named route "rss_messages". + +member + + Additional URLs to allow for a member. Example:: + + map.resource('message', 'messages', member={'mark':'POST'}) + # "POST /message/1/mark" => ``Messages.mark(1)`` + # also adds named route "mark_message" + + This can be used to display a delete confirmation form:: + + map.resource("message", "messages", member={"ask_delete": "GET"} + # "GET /message/1/ask_delete" => ``Messages.ask_delete(1)``. + # Also adds a named route "ask_delete_message". + +new + + Additional URLs to allow for new-member functionality. :: + + map.resource("message", "messages", new={"preview": "POST"}) + # "POST /messages/new/preview" + +path_prefix + + Prepend the specified prefix to all URL patterns. The prefix may include + path variables. This is mainly used to nest resources within resources. + +name_prefix + + Prefix the specified string to all route names. This is most often + combined with ``path_prefix`` to nest resources:: + + map.resource("message", "messages", controller="categories", + path_prefix="/category/{category_id}", + name_prefix="category_") + # GET /category/7/message/1 + # Adds named route "category_message" + +parent_resource + + A dict containing information about the parent resource, for creating a + nested resource. It should contain the member_name and collection_name + of the parent resource. This dict will be available via the associated + Route object which can be accessed during a request via + ``request.environ["routes.route"]``. + + If parent_resource is supplied and path_prefix isn't, path_prefix will + be generated from parent_resource as "<parent collection name>/:<parent + member name>_id". + + If parent_resource is supplied and name_prefix isn't, name_prefix will + be generated from parent_resource as "<parent member name>_". + + Example:: + + >>> from routes.util import url_for + >>> m = Mapper() + >>> m.resource('location', 'locations', + ... parent_resource=dict(member_name='region', + ... collection_name='regions')) + >>> # path_prefix is "regions/:region_id" + >>> # name prefix is "region_" + >>> url_for('region_locations', region_id=13) + '/regions/13/locations' + >>> url_for('region_new_location', region_id=13) + '/regions/13/locations/new' + >>> url_for('region_location', region_id=13, id=60) + '/regions/13/locations/60' + >>> url_for('region_edit_location', region_id=13, id=60) + '/regions/13/locations/60/edit' + + Overriding generated path_prefix: + + >>> m = Mapper() + >>> m.resource('location', 'locations', + ... parent_resource=dict(member_name='region', + ... collection_name='regions'), + ... path_prefix='areas/:area_id') + >>> # name prefix is "region_" + >>> url_for('region_locations', area_id=51) + '/areas/51/locations' + + Overriding generated name_prefix: + + >>> m = Mapper() + >>> m.resource('location', 'locations', + ... parent_resource=dict(member_name='region', + ... collection_name='regions'), + ... name_prefix='') + >>> # path_prefix is "regions/:region_id" + >>> url_for('locations', region_id=51) + '/regions/51/locations' + + +Redirect routes +=============== + +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. + +``map.redirect`` 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 ``map.connect``, both in regards to extra variables and to route +options. :: + + map.redirect("/legacyapp/archives/{url:.*}", "/archives/{url}") + + map.redirect("/legacyapp/archives/{url:.*}", "/archives/{url}") + +By default a "302 Found" HTTP status is issued. You can override this with the +``_redirect_code`` keyword argument. The value must be an entire status +string. :: + + map.redirect("/home/index", "/", _redirect_code="301 Moved Permanently") + +Redirect routes are new in Routes 1.10. + +Other +===== + +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. + +Using Routes with Pylons and WebHelpers +======================================= + +As mentioned above, Pylons applications should define their routes in the +``make_map`` function in *myapp/config/routing.py*. + +Templates can use ``h.url(...)`` to generate URLs (starting with Pylons 0.9.7), +or the older ``h.url_for(...)``. Controllers will have to import these to use +them:: + + from pylons import url + from routes import url_for + from pylons.controllers.util import redirect_to + +Previously, ``url_for`` and ``redirect_to`` were imported via WebHelpers by +this line in *myapp/lib/helpers.py*: "from webhelpers.rails import \*". +``webhelpers.rails`` is deprecated and will soon be removed. If you want to +use ``url_for`` or ``redirect_to``, import them as shown above. + +Routes is implemented in Pylons using the RoutesMiddleware, which is activated +in *myapp/config/middleware.py*. + +To debug routes, turn on debug logging for the "routes.middleware" logger. + + +Porting Routes to other frameworks +================================== + +An application can create a raw mapper object and call its ``.match`` and +``.generate`` methods. However, WSGI applications will probably want to use +the ``RoutesMiddleware`` as Pylons does:: + + # In myapp/config/middleware.py + from routes.middleware import RoutesMiddleware + app = RoutesMiddleware(app, map) # ``map`` is a routes.Mapper. + +The middleware matches the requested URL and sets the following WSGI +variables:: + + environ['wsgiorg.routing_args'] = ((url, match)) + environ['routes.route'] = route + environ['routes.url'] = url + +where ``match`` is the routing variables dict, ``route`` is the matched route, +and ``url`` is a ``URLGenerator`` object. In Pylons, ``match`` is used by the +dispatcher, and ``url`` is accessible as ``pylons.url``. + +The middleware handles redirect routes itself, issuing the appropriate +redirect. The application is not called in this case. + +To debug routes, turn on debug logging for the "routes.middleware" logger. + +See the Routes source for other features which may have been added. + +URL Resolution +-------------- + +When the URL is looked up, it should be matched against the Mapper. When +matching an incoming URL, it is assumed that the URL path is the only string +being matched. All query args should be stripped before matching:: + + m.connect('articles/{year}/{month}', controller='blog', action='view', year=None) + + m.match('/articles/2003/10') + # {'controller':'blog', 'action':'view', 'year':'2003', 'month':'10'} + +Matching a URL will return a dict of the match results, if you'd like to +differentiate between where the argument came from you can use routematch which +will return the Route object that has all these details:: + + m.connect('articles/{year}/{month}', controller='blog', action='view', year=None) + + result = m.routematch('/articles/2003/10') + # result is a tuple of the match dict, and the Route object + + # result[0] - {'controller':'blog', 'action':'view', 'year':'2003', 'month':'10'} + # result[1] - Route object + # result[1].defaults - {'controller':'blog', 'action':'view', 'year':None} + # result[1].hardcoded - ['controller', 'action'] + +Your integration code is then expected to dispatch to a controller and action +in the dict. How it does this is entirely up to the framework integrator. Your +integration should also typically provide the web developer a mechanism to +access the additional dict values. + +Setting up the Request Configuration +------------------------------------ + +Before you dispatch the request to the Controller, a few things need to be +configured to ensure that the redirect_to and url_for function properly. + +A special thread-safe singleton class is used to hold this information:: + + from routes import request_config + + config = request_config() + + config.mapper = m # Your mapper object + config.mapper_dict = result # The dict from m.match for this URL request + config.host = hostname # The server hostname + config.protocol = port # Protocol used, http, https, etc. + config.redirect = redir_func # A redirect function used by your framework, that is + # expected to take as the first non-keyword arg a single + # full or relative URL + +Reference the docs for request_config when setting this object up to ensure +you've initialized everything needed. + +This object needs to be configured for every request before controller dispatch. + |