### Navigation

- index
- modules |
- next |
- previous |
- TurboGears 2.1.5 documentation »
- Search:
- Extended Table of Contents »
- The Gears in Detail »
- Third-party components »

# `routes` – Route and Mapper core classes

## `routes.mapper`

Mapper and Sub-Mapper

class `routes.mapper.``Mapper`(controller_scan=<function controller_scan at 0x99323ac>, directory=None, always_scan=False, register=True, explicit=True)

  Mapper handles URL generation and URL recognition in a web application.

  Mapper is built handling dictionary’s. It is assumed that the web application will handle the dictionary returned by URL recognition to dispatch appropriately.

  URL generation is done by passing keyword parameters into the generate function, a URL is then returned.

  `__init__`(controller_scan=<function controller_scan at 0x99323ac>, directory=None, always_scan=False, register=True, explicit=True)

    Create a new Mapper instance

    All keyword arguments are optional.

    `controller_scan`

      Function reference that will be used to return a list of valid controllers used during URL matching. If `directory` keyword arg is present, it will be passed into the function during its call. This option defaults to a function that will scan a directory for controllers.

      Alternatively, a list of controllers or None can be passed in which are assumed to be the definitive list of controller names valid when matching ‘controller’.

    `directory`
      Passed into controller_scan for the directory to scan. It should be an absolute path if using the default `controller_scan` function.
    `always_scan`
      Whether or not the `controller_scan` function should be run during every URL match. This is typically a good idea during development so the server won’t need to be restarted anytime a controller is added.
    `register`
      Boolean used to determine if the Mapper should use `request_config` to register itself as the mapper. Since it’s done on a thread-local basis, this is typically best used during testing though it won’t hurt in other cases.
    `explicit`

      Boolean used to determine if routes should be connected with implicit defaults of:

          {'controller':'content','action':'index','id':None}

      When set to True, these defaults will not be added to route connections and `url_for` will not use Route memory.

    Additional attributes that may be set after mapper initialization (ie, map.ATTRIBUTE = ‘something’):

    `encoding`
      Used to indicate alternative encoding/decoding systems to use with both incoming URL’s, and during Route generation when passed a Unicode string. Defaults to ‘utf-8’.
    `decode_errors`
      How to handle errors in the encoding, generally ignoring any chars that don’t convert should be sufficient. Defaults to ‘ignore’.
    `minimization`
      Boolean used to indicate whether or not Routes should minimize URL’s and the generated URL’s, or require every part where it appears in the path. Defaults to True.
    `hardcode_names`
      Whether or not Named Routes result in the default options for the route being used or if they actually force url generation to use the route. Defaults to False.
  `connect`(*args, **kargs)

    Create and connect a new Route to the Mapper.

    Usage:

        m = Mapper()
        m.connect(':controller/:action/:id')
        m.connect('date/:year/:month/:day', controller="blog", action="view")
        m.connect('archives/:page', controller="blog", action="by_page",
        requirements = { 'page':'\d{1,2}' })
        m.connect('category_list', 'archives/category/:section', controller='blog', action='category',
        section='home', type='list')
        m.connect('home', '', controller='blog', action='view', section='home')

  `create_regs`(*args, **kwargs)

    Atomically creates regular expressions for all connected routes

  `extend`(routes, path_prefix='')

    Extends the mapper routes with a list of Route objects

    If a path_prefix is provided, all the routes will have their path prepended with the path_prefix.

    Example:

        >>> map = Mapper(controller_scan=None)
        >>> map.connect('home', '/', controller='home', action='splash')
        >>> map.matchlist[0].name == 'home'
        True
        >>> routes = [Route('index', '/index.htm', controller='home',
        ...                 action='index')]
        >>> map.extend(routes)
        >>> len(map.matchlist) == 2
        True
        >>> map.extend(routes, path_prefix='/subapp')
        >>> len(map.matchlist) == 3
        True
        >>> map.matchlist[2].routepath == '/subapp/index.htm'
        True

    Note

    This function does not merely extend the mapper with the given list of routes, it actually creates new routes with identical calling arguments.

  `generate`(*args, **kargs)

    Generate a route from a set of keywords

    Returns the url text, or None if no URL could be generated.

        m.generate(controller='content',action='view',id=10)

  `match`(url=None, environ=None)

    Match a URL against against one of the routes contained.

    Will return None if no valid match is found.

        resultdict = m.match('/joe/sixpack')

  `redirect`(match_path, destination_path, *args, **kwargs)

    Add a redirect route to the mapper

    Redirect routes bypass the wrapped WSGI application and instead result in a redirect being issued by the RoutesMiddleware. As such, this method is only meaningful when using RoutesMiddleware.

    By default, a 302 Found status code is used, this can be changed by providing a `_redirect_code` keyword argument which will then be used instead. Note that the entire status code string needs to be present.

    When using keyword arguments, all arguments that apply to matching will be used for the match, while generation specific options will be used during generation. Thus all options normally available to connected Routes may be used with redirect routes as well.

    Example:

        map = Mapper()
        map.redirect('/legacyapp/archives/{url:.*}, '/archives/{url})
        map.redirect('/home/index', '/', _redirect_code='301 Moved Permanently')

  `resource`(member_name, collection_name, **kwargs)

    Generate routes for a controller resource

    The member_name name should be the appropriate singular version of the resource given your locale and used with members of the collection. The collection_name name will be used to refer to the resource collection methods and should be a plural version of the member_name argument. By default, the member_name name will also be assumed to map to a controller you create.

    The concept of a web resource maps somewhat directly to ‘CRUD’ operations. The overlying things to keep in mind is that mapping a resource is about handling creating, viewing, and editing that resource.

    All keyword arguments are optional.

    `controller`
      If specified in the keyword args, the controller will be the actual controller used, but the rest of the naming conventions used for the route names and URL paths are unchanged.
    `collection`

      Additional action mappings used to manipulate/view the entire set of resources provided by the controller.

      Example:

          map.resource('message', 'messages', collection={'rss':'GET'})
          # GET /message/rss (maps to the rss action)
          # also adds named route "rss_message"

    `member`

      Additional action mappings used to access an individual ‘member’ of this controllers resources.

      Example:

          map.resource('message', 'messages', member={'mark':'POST'})
          # POST /message/1/mark (maps to the mark action)
          # also adds named route "mark_message"

    `new`

      Action mappings that involve dealing with a new member in the controller resources.

      Example:

          map.resource('message', 'messages', new={'preview':'POST'})
          # POST /message/new/preview (maps to the preview action)
          # also adds a url named "preview_new_message"

    `path_prefix`
      Prepends the URL path for the Route with the path_prefix given. This is most useful for cases where you want to mix resources or relations between resources.
    `name_prefix`

      Perpends the route names that are generated with the name_prefix given. Combined with the path_prefix option, it’s easy to generate route names and paths that represent resources that are in relations.

      Example:

          map.resource('message', 'messages', controller='categories',
              path_prefix='/category/:category_id',
              name_prefix="category_")
          # GET /category/7/message/1
          # has 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'

  `routematch`(url=None, environ=None)

    Match a URL against against one of the routes contained.

    Will return None if no valid match is found, otherwise a result dict and a route object is returned.

        resultdict, route_obj = m.match('/joe/sixpack')

## `routes.route`

class `routes.route.``Route`(name, routepath, **kargs)

  The Route object holds a route recognition and generation routine.

  See Route.__init__ docs for usage.

  `__init__`(name, routepath, **kargs)

    Initialize a route, with a given routepath for matching/generation

    The set of keyword args will be used as defaults.

    Usage:

        >>> from routes.base import Route
        >>> newroute = Route(None, ':controller/:action/:id')
        >>> sorted(newroute.defaults.items())
        [('action', 'index'), ('id', None)]
        >>> newroute = Route(None, 'date/:year/:month/:day',
        ...     controller="blog", action="view")
        >>> newroute = Route(None, 'archives/:page', controller="blog",
        ...     action="by_page", requirements = { 'page':'\d{1,2}' })
        >>> newroute.reqs
        {'page': '\\d{1,2}'}

    Note

    Route is generally not called directly, a Mapper instance connect method should be used to add routes.

  `buildfullreg`(clist, include_names=True)

    Build the regexp by iterating through the routelist and replacing dicts with the appropriate regexp match

  `buildnextreg`(path, clist, include_names=True)

    Recursively build our regexp given a path, and a controller list.

    Returns the regular expression string, and two booleans that can be ignored as they’re only used internally by buildnextreg.

  `generate`(_ignore_req_list=False, _append_slash=False, **kargs)

    Generate a URL from ourself given a set of keyword arguments

    Toss an exception if this set of keywords would cause a gap in the url.

  `generate_minimized`(kargs)

    Generate a minimized version of the URL

  `generate_non_minimized`(kargs)

    Generate a non-minimal version of the URL

  `make_full_route`()

    Make a full routelist string for use with non-minimized generation

  `make_unicode`(s)

    Transform the given argument into a unicode string.

  `makeregexp`(clist, include_names=True)

    Create a regular expression for matching purposes

    Note: This MUST be called before match can function properly.

    clist should be a list of valid controller strings that can be matched, for this reason makeregexp should be called by the web framework after it knows all available controllers that can be utilized.

    include_names indicates whether this should be a match regexp assigned to itself using regexp grouping names, or if names should be excluded for use in a single larger regexp to determine if any routes match

  `match`(url, environ=None, sub_domains=False, sub_domains_ignore=None, domain_match='')

    Match a url to our regexp.

    While the regexp might match, this operation isn’t guaranteed as there’s other factors that can cause a match to fail even though the regexp succeeds (Default that was relied on wasn’t given, requirement regexp doesn’t pass, etc.).

    Therefore the calling function shouldn’t assume this will return a valid dict, the other possible return is False if a match doesn’t work out.

## `routes.util`

Utility functions for use in templates / controllers

PLEASE NOTE: Many of these functions expect an initialized RequestConfig object. This is expected to have been initialized for EACH REQUEST by the web framework.

`routes.util.``url_for`(*args, **kargs)

  Generates a URL

  All keys given to url_for are sent to the Routes Mapper instance for generation except for:

      anchor          specified the anchor name to be appened to the path
      host            overrides the default (current) host if provided
      protocol        overrides the default (current) protocol if provided
      qualified       creates the URL with the host/port information as
                      needed

  The URL is generated based on the rest of the keys. When generating a new URL, values will be used from the current request’s parameters (if present). The following rules are used to determine when and how to keep the current requests parameters:

  - If the controller is present and begins with ‘/’, no defaults are used
  - If the controller is changed, action is set to ‘index’ unless otherwise specified

  For example, if the current request yielded a dict of {‘controller’: ‘blog’, ‘action’: ‘view’, ‘id’: 2}, with the standard ‘:controller/:action/:id’ route, you’d get the following results:

      url_for(id=4)                    =>  '/blog/view/4',
      url_for(controller='/admin')     =>  '/admin',
      url_for(controller='admin')      =>  '/admin/view/2'
      url_for(action='edit')           =>  '/blog/edit/2',
      url_for(action='list', id=None)  =>  '/blog/list'

  Static and Named Routes

  If there is a string present as the first argument, a lookup is done against the named routes table to see if there’s any matching routes. The keyword defaults used with static routes will be sent in as GET query arg’s if a route matches.

  If no route by that name is found, the string is assumed to be a raw URL. Should the raw URL begin with `/` then appropriate SCRIPT_NAME data will be added if present, otherwise the string will be used as the url with keyword args becoming GET query args.

`routes.util.``redirect_to`(*args, **kargs)

  Issues a redirect based on the arguments.

  Redirect’s should occur as a “302 Moved” header, however the web framework may utilize a different method.

  All arguments are passed to url_for to retrieve the appropriate URL, then the resulting URL it sent to the redirect function as the URL.