home » snippets » python » tipfy » urls

Links

• Werkzeug URL Routing
• Tipfy URL Routing – hardly anything here.
• See "class Rule" in routing.py

Notes

• endpoint and name are interchangeable. endpoint is the name of the param as used by werkzeug.
• Set handler_method to avoid calling by request.method (such as "GET/POST" etc.)
• Handler can either be a class or a function.
  • If it's a class, it's called with the request to construct the instance and called again with nothing to get the response.
  • If it's a function, it's just called once with the request object.

Rule Params

path

Rule strings basically are just normal URL paths with placeholders in the format <converter(arguments):name> where the converter and the arguments are optional. If no converter is defined the default converter is used which means string in the normal configuration.

URL rules that end with a slash are branch URLs, others are leaves. If you have strict_slashes enabled (which is the default), all branch URLs that are matched without a trailing slash will trigger a redirect to the same URL with the missing slash appended.

The converters are defined on the Map.

name

The rule name used for URL generation.

handler

The handler class or function used to handle requests when this rule matches. Can be defined as a string to be lazily imported.

handler_method

The method to be executed from the handler class. If not defined, defaults to the current request method in lower case.

defaults

An optional dict with defaults for other rules with the same endpoint. This is a bit tricky but useful if you want to have unique URLs::

rules = [
    Rule('/all/', name='pages', handler='handlers.PageHandler', defaults={'page': 1}),
    Rule('/all/page/<int:page>', name='pages', handler='handlers.PageHandler'),
]

If a user now visits http://example.com/all/page/1 he will be redirected to http://example.com/all/. If redirect_defaults is disabled on the Map instance this will only affect the URL generation.

subdomain

The subdomain rule string for this rule. If not specified the rule only matches for the default_subdomain of the map. If the map is not bound to a subdomain this feature is disabled.

Can be useful if you want to have user profiles on different subdomains and all subdomains are forwarded to your application.

methods

A sequence of http methods this rule applies to. If not specified, all methods are allowed. For example this can be useful if you want different endpoints for POST and GET. If methods are defined and the path matches but the method matched against is not in this list or in the list of another rule for that path the error raised is of the type MethodNotAllowed rather than NotFound. If GET is present in the list of methods and HEAD is not, HEAD is added automatically.

strict_slashes

Override the Map setting for strict_slashes only for this rule. If not specified the Map setting is used.

build_only

Set this to True and the rule will never match but will create a URL that can be build. This is useful if you have resources on a subdomain or folder that are not handled by the WSGI application (like static data).

redirect_to

If given this must be either a string or callable. In case of a callable it's called with the url adapter that triggered the match and the values of the URL as keyword arguments and has to return the target for the redirect, otherwise it has to be a string with placeholders in rule syntax::

def foo_with_slug(adapter, id):
    # ask the database for the slug for the old id. this of
    # course has nothing to do with werkzeug.
    return 'foo/' + Foo.get_slug_for_id(id)

rules = [
    Rule('/foo/<slug>', name='foo', handler='handlers.FooHandler'),
    Rule('/some/old/url/<slug>', redirect_to='foo/<slug>'),
    Rule('/other/old/url/<int:id>', redirect_to=foo_with_slug)
]

When the rule is matched the routing system will raise a RequestRedirect exception with the target for the redirect.

Keep in mind that the URL will be joined against the URL root of the script so don't use a leading slash on the target URL unless you really mean root of that domain.