rewrite Module

This file is part of the web2py Web Framework
Copyrighted by Massimo Di Pierro <>

gluon.rewrite parses incoming URLs and formats outgoing URLs for gluon.html.URL.

In addition, it rewrites both incoming and outgoing URLs based on the (optional) user-supplied, which also allows for rewriting of certain error messages. supports two styles of URL rewriting, depending on whether ‘routers’ is defined. Refer to and for additional documentation.

class gluon.rewrite.MapUrlIn(request=None, env=None)[source]

Bases: object

Logic for mapping incoming URLs


Returns first arg


Returns first arg with optional hyphen mapping


Determines application name


Identifies controller


Handles function.extension


Handles language (no hyphen mapping)


Strips path prefix, if present in its entirety


Handles root-static files (no hyphen mapping)

a root-static file is one whose incoming URL expects it to be at the root, typically robots.txt & favicon.ico


Handles static files file_match but no hyphen mapping


Conditionally removes first arg and returns new first arg


Updates request from self Builds env.request_uri Makes lower-case versions of http headers in env


Checks args against validation pattern

class gluon.rewrite.MapUrlOut(request, env, application, controller, function, args, other, scheme, host, port, language)[source]

Bases: object

Logic for mapping outgoing URLs


Converts components to /app/lang/controller/function


Builds a/c/f from components


Omits what we can of a/c/f


Omits language if possible

gluon.rewrite.compile_regex(k, v, env=None)[source]

Preprocess and compile the regular expressions in routes_app/in/out The resulting regex will match a pattern of the form:

[remote address]:[protocol]://[host]:[method] [path]

We allow abbreviated regexes on input; here we try to complete them.

gluon.rewrite.filter_err(status, application='app', ticket='tkt')[source]

doctest/unittest interface to routes_onerror

gluon.rewrite.filter_url(url, method='get', remote='', out=False, app=False, lang=None, domain=(None, None), env=False, scheme=None, host=None, port=None, language=None)[source]

doctest/unittest interface to regex_filter_in() and regex_filter_out()


Returns a private copy of the effective router for the specified application

gluon.rewrite.load(routes='', app=None, data=None, rdict=None)[source]

load: read (if file) and parse routes store results in params (called from at web2py initialization time) If data is present, it’s used instead of the contents. If rdict is present, it must be a dict to be used for routers (unit test)


Load-time post-processing of routers


Log rewrite activity under control of

gluon.rewrite.map_url_in(request, env, app=False)[source]

Routes incoming URL

gluon.rewrite.map_url_out(request, env, application, controller, function, args, other, scheme, host, port, language=None)[source]

Supply /a/c/f (or /a/lang/c/f) portion of outgoing url

The basic rule is that we can only make transformations that map_url_in can reverse.

Suppose that the incoming arguments are a,c,f,args,lang and that the router defaults are da, dc, df, dl.

We can perform these transformations trivially if args=[] and lang=None or dl:

/da/dc/df => /
/a/dc/df => /a
/a/c/df => /a/c

We would also like to be able to strip the default application or application/controller from URLs with function/args present, thus:

/da/c/f/args  => /c/f/args
/da/dc/f/args => /f/args

We use [applications] and [controllers] and {functions} to suppress ambiguous omissions.

We assume that language names do not collide with a/c/f names.


Regex rewrite incoming URL

gluon.rewrite.regex_filter_out(url, e=None)[source]

Regex rewrite outgoing URL

gluon.rewrite.regex_select(env=None, app=None, request=None)[source]

Selects a set of regex rewrite params for the current request

gluon.rewrite.regex_uri(e, regexes, tag, default=None)[source]

Filters incoming URI against a list of regexes

gluon.rewrite.regex_url_in(request, environ)[source]

Rewrites and parses incoming URL

gluon.rewrite.try_redirect_on_error(http_object, request, ticket=None)[source]

Called from main.wsgibase to rewrite the http response

gluon.rewrite.try_rewrite_on_error(http_response, request, environ, ticket=None)[source]

Called from main.wsgibase to rewrite the http response.

gluon.rewrite.url_in(request, environ)[source]

Parses and rewrites incoming URL

gluon.rewrite.url_out(request, environ, application, controller, function, args, other, scheme, host, port, language=None)[source]

Assembles and rewrites outgoing URL