webtools.route

URI building and routing classes. Ported from webapp2, refactored to support Python versions > 2.7, 3.0

class webtools.route.BaseRoute(uri_template, handler=None, name=None, build_only=False)

Interface for URI routes.

handler_method = None

The custom handler method, if handler is a class.

handler_adapter = None

The handler, imported and ready for dispatching.

uri_template = None

The uri regex template.

handler = None

The handler or string in dotted notation to be lazily imported.

name = None

Route name, used to build URIs.

build_only = False

True if this route is only used for URI generation and never matches.

match(request)

Matches all routes against a request object.

The first one that matches is returned.

Parameters:request – A Request instance.
Returns:A tuple (route, args, kwargs) if a route matched, or None.
build(request, args, kwargs)

Returns a URI for this route.

Parameters:
  • request – The current Request object.
  • args – Tuple of positional arguments to build the URI.
  • kwargs – Dictionary of keyword arguments to build the URI.
Returns:

An absolute or relative URI.

get_routes()

Generator to get all routes from a route.

Yields:This route or all nested routes that it contains.
get_match_routes()

Generator to get all routes that can be matched from a route.

Match routes must implement match().

Yields:This route or all nested routes that can be matched.
get_build_routes()

Generator to get all routes that can be built from a route.

Build routes must implement build().

Yields:A tuple (name, route) for all nested routes that can be built.
class webtools.route.SimpleRoute(uri_template, handler=None, name=None, build_only=False)

A route that is compatible with webapp’s routing mechanism.

URI building is not implemented as webapp has rudimentar support for it, and this is the most unknown webapp feature anyway.

regex

Lazy regex compiler.

match(request)

Matches this route against the current request.

See also

BaseRoute.match().

class webtools.route.Route(uri_template, handler=None, name=None, defaults=None, build_only=False, handler_method=None, methods=None, schemes=None)

A route definition that maps a URI path to a handler.

The initial concept was based on Another Do-It-Yourself Framework, by Ian Bicking.

defaults = None

Default parameters values.

methods = None

Sequence of allowed HTTP methods. If not set, all methods are allowed.

schemes = None

Sequence of allowed URI schemes. If not set, all schemes are allowed.

regex

Lazy route template parser.

match(request)

Matches this route against the current request.

Raises:exc.HTTPMethodNotAllowed if the route defines methods and the request method isn’t allowed.

See also

BaseRoute.match().

build(request, args, kwargs)

Returns a URI for this route.

See also

Router.build().

class webtools.route.Router(routes=None)

A URI router used to match, dispatch and build URIs.

route_class

Class used when the route is set as a tuple.

alias of SimpleRoute

match_routes = None

All routes that can be matched.

build_routes = None

All routes that can be built.

handlers = None

Handler classes imported lazily.

add(route)

Adds a route to this router.

Parameters:route – A Route instance or, for simple routes, a tuple (regex, handler).
set_matcher(func)

Sets the function called to match URIs.

Parameters:func – A function that receives (router, request) and returns a tuple (route, args, kwargs) if any route matches, or raise exc.HTTPNotFound if no route matched or exc.HTTPMethodNotAllowed if a route matched but the HTTP method was not allowed.
set_builder(func)

Sets the function called to build URIs.

Parameters:func – A function that receives (router, request, name, args, kwargs) and returns a URI.
set_dispatcher(func)

Sets the function called to dispatch the handler.

Parameters:func – A function that receives (router, request, response) and returns the value returned by the dispatched handler.
set_adapter(func)

Sets the function that adapts loaded handlers for dispatching.

Parameters:func – A function that receives (router, handler) and returns a handler callable.
default_matcher(request)

Matches all routes against a request object.

The first one that matches is returned.

Parameters:request – A Request instance.
Returns:A tuple (route, args, kwargs) if a route matched, or None.
Raises:exc.HTTPNotFound if no route matched or exc.HTTPMethodNotAllowed if a route matched but the HTTP method was not allowed.
default_builder(request, name, args, kwargs)

Returns a URI for a named Route.

Parameters:
  • request – The current Request object.
  • name – The route name.
  • args – Tuple of positional arguments to build the URI. All positional variables defined in the route must be passed and must conform to the format set in the route. Extra arguments are ignored.
  • kwargs

    Dictionary of keyword arguments to build the URI. All variables not set in the route default values must be passed and must conform to the format set in the route. Extra keywords are appended as a query string.

    A few keywords have special meaning:

    • _full: If True, builds an absolute URI.
    • _scheme: URI scheme, e.g., http or https. If defined, an absolute URI is always returned.
    • _netloc: Network location, e.g., www.google.com. If defined, an absolute URI is always returned.
    • _fragment: If set, appends a fragment (or “anchor”) to the generated URI.
Returns:

An absolute or relative URI.

default_dispatcher(request, response)

Dispatches a handler.

Parameters:
  • request – A Request instance.
  • response – A Response instance.
Raises:

exc.HTTPNotFound if no route matched or exc.HTTPMethodNotAllowed if a route matched but the HTTP method was not allowed.

Returns:

The returned value from the handler.

default_adapter(handler)

Adapts a handler for dispatching.

Because handlers use or implement different dispatching mechanisms, they can be wrapped to use a unified API for dispatching. This way webapp2 can support, for example, a RequestHandler class and function views or, for compatibility purposes, a webapp.RequestHandler class. The adapters follow the same router dispatching API but dispatch each handler type differently.

Parameters:handler – A handler callable.
Returns:A wrapped handler callable.
match(request)

Matches all routes against a request object.

The first one that matches is returned.

Parameters:request – A Request instance.
Returns:A tuple (route, args, kwargs) if a route matched, or None.
Raises:exc.HTTPNotFound if no route matched or exc.HTTPMethodNotAllowed if a route matched but the HTTP method was not allowed.
build(request, name, args, kwargs)

Returns a URI for a named Route.

Parameters:
  • request – The current Request object.
  • name – The route name.
  • args – Tuple of positional arguments to build the URI. All positional variables defined in the route must be passed and must conform to the format set in the route. Extra arguments are ignored.
  • kwargs

    Dictionary of keyword arguments to build the URI. All variables not set in the route default values must be passed and must conform to the format set in the route. Extra keywords are appended as a query string.

    A few keywords have special meaning:

    • _full: If True, builds an absolute URI.
    • _scheme: URI scheme, e.g., http or https. If defined, an absolute URI is always returned.
    • _netloc: Network location, e.g., www.google.com. If defined, an absolute URI is always returned.
    • _fragment: If set, appends a fragment (or “anchor”) to the generated URI.
Returns:

An absolute or relative URI.

dispatch(request, response)

Dispatches a handler.

Parameters:
  • request – A Request instance.
  • response – A Response instance.
Raises:

exc.HTTPNotFound if no route matched or exc.HTTPMethodNotAllowed if a route matched but the HTTP method was not allowed.

Returns:

The returned value from the handler.

adapt(handler)

Adapts a handler for dispatching.

Because handlers use or implement different dispatching mechanisms, they can be wrapped to use a unified API for dispatching. This way webapp2 can support, for example, a RequestHandler class and function views or, for compatibility purposes, a webapp.RequestHandler class. The adapters follow the same router dispatching API but dispatch each handler type differently.

Parameters:handler – A handler callable.
Returns:A wrapped handler callable.

Previous topic

webtools.wsgi

Next topic

webtools.handlers

This Page