# `routes.util` – URL Generator and utility functions

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.

## Module Contents

exception routes.util.RoutesException

  Tossed during Route exceptions

exception routes.util.MatchException

  Tossed during URL matching exceptions

exception routes.util.GenerationException

  Tossed during URL generation exceptions

class routes.util.URLGenerator(mapper, environ)

  The URL Generator generates URL’s

  It is automatically instantiated by the RoutesMiddleware and put into the `wsgiorg.routing_args` tuple accessible as:

      url = environ['wsgiorg.routing_args'][0][0]

  Or via the `routes.url` key:

      url = environ['routes.url']

  The url object may be instantiated outside of a web context for use in testing, however sub_domain support and fully qualified URL’s cannot be generated without supplying a dict that must contain the key `HTTP_HOST`.

  Instantiate the URLGenerator

  `mapper`

    The mapper object to use when generating routes.

  `environ`

    The environment dict used in WSGI, alternately, any dict that contains at least an `HTTP_HOST` value.

  current(*args, **kwargs)

    Generate a route that includes params used on the current request

    The arguments for this method are identical to `__call__` except that arguments set to None will remove existing route matches of the same name from the set of arguments used to construct a URL.

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._url_quote(string, encoding)

  A Unicode handling version of urllib.quote.

routes.util._str_encode(string, encoding)

routes.util._screenargs(kargs, mapper, environ, force_explicit=False)

  Private function that takes a dict, and screens it against the current request dict to determine what the dict should look like that is used. This is responsible for the requests “memory” of the current.

routes.util._subdomain_check(kargs, mapper, environ)

  Screen the kargs for a subdomain and alter it appropriately depending on the current subdomain or lack therof.