webapp2

• WSGI app
  • WSGIApplication
  • RequestContext
• URI routing
  • Router
  • BaseRoute
  • SimpleRoute
  • Route
• Configuration
  • Config
• Request and Response
  • Request
  • Response
• Request handlers
  • RequestHandler
  • RedirectHandler
• Utilities
  • cached_property
  • get_app()
  • get_request()
  • redirect()
  • redirect_to()
  • uri_for()
  • abort()
  • import_string()
  • urlunsplit()

WSGI app

See also

The WSGI application

class webapp2.WSGIApplication(routes=None, debug=False, config=None)

A WSGI-compliant application.

__call__(environ, start_response)

Called by WSGI when a request comes in.

Parameters:

• environ – A WSGI environment.
• start_response – A callable accepting a status code, a list of headers and an optional exception context to start the response.

Returns:

An iterable with the response to return to the client.

__init__(routes=None, debug=False, config=None)

Initializes the WSGI application.

Parameters:

• routes – A sequence of Route instances or, for simple routes, tuples (regex, handler).
• debug – True to enable debug mode, False otherwise.
• config – A configuration dictionary for the application.

active_instance = <LocalProxy unbound>

Same as app, for webapp compatibility. See set_globals().

allowed_methods = frozenset(['HEAD', 'TRACE', 'GET', 'PUT', 'POST', 'OPTIONS', 'DELETE'])

Allowed request methods.

app = <LocalProxy unbound>

Active WSGIApplication instance. See set_globals().

clear_globals()

Clears global variables. See set_globals().

config = None

A Config instance with the application configuration.

config_class

Class used for the configuration object.

alias of Config

debug = False

A general purpose flag to indicate development mode: if True, uncaught exceptions are raised instead of using HTTPInternalServerError.

error_handlers = None

A dictionary mapping HTTP error codes to callables to handle those HTTP exceptions. See handle_exception().

get_response(*args, **kwargs)

Creates a request and returns a response for this app.

This is a convenience for unit testing purposes. It receives parameters to build a request and calls the application, returning the resulting response:

class HelloHandler(webapp2.RequestHandler):
    def get(self):
        self.response.write('Hello, world!')

app = webapp2.WSGIapplication([('/', HelloHandler)])

# Test the app, passing parameters to build a request.
response = app.get_response('/')
assert response.status_int == 200
assert response.body == 'Hello, world!'

Parameters:

• args – Positional arguments to be passed to Request.blank().
• kwargs – Keyword arguments to be passed to Request.blank().

Returns:

A Response object.

handle_exception(request, response, e)

Handles a uncaught exception occurred in __call__().

Uncaught exceptions can be handled by error handlers registered in error_handlers. This is a dictionary that maps HTTP status codes to callables that will handle the corresponding error code. If the exception is not an HTTPException, the status code 500 is used.

The error handlers receive (request, response, exception) and can be a callable or a string in dotted notation to be lazily imported.

If no error handler is found, the exception is re-raised.

Based on idea from Flask.

Parameters:

• request – A Request instance.
• response – A Response instance.
• e – The uncaught exception.

Returns:

The returned value from the error handler.

registry = None

A dictionary to register objects used during the app lifetime.

request = <LocalProxy unbound>

Active Request instance. See set_globals().

request_class

Class used for the request object.

alias of Request

request_context_class

Class used for the request context object.

alias of RequestContext

response_class

Class used for the response object.

alias of Response

router = None

A Router instance with all URIs registered for the application.

router_class

Class used for the router object.

alias of Router

run(bare=False)

Runs this WSGI-compliant application in a CGI environment.

This uses functions provided by google.appengine.ext.webapp.util, if available: run_bare_wsgi_app and run_wsgi_app.

Otherwise, it uses wsgiref.handlers.CGIHandler().run().

Parameters:bare – If True, doesn’t add registered WSGI middleware: use run_bare_wsgi_app instead of run_wsgi_app.

set_globals(app=None, request=None)

Registers the global variables for app and request.

If webapp2_extras.local is available, the app and request class attributes are assigned to a proxy object that returns them using thread-local, making the application thread-safe. This can also be used in environments that don’t support threading.

If webapp2_extras.local is not available, app and request will be assigned directly as class attributes. This should only be used in non-threaded environments (e.g., App Engine Python 2.5).

Parameters:

• app – A WSGIApplication instance.
• request – A Request instance.

class webapp2.RequestContext(app, environ)

Context for a single request.

The context is responsible for setting and cleaning global variables for a request.

__enter__()

Enters the request context.

Returns:A tuple (request, response).

__exit__(exc_type, exc_value, traceback)

Exits the request context.

This release the context locals except if an exception is caught in debug mode. In this case they are kept to be inspected.

__init__(app, environ)

Initializes the request context.

Parameters:

• app – An WSGIApplication instance.
• environ – A WSGI environment dictionary.

URI routing

See also

Router and URI routing

class webapp2.Router(routes=None)

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

__init__(routes=None)

Initializes the router.

Parameters:routes – A sequence of Route instances or, for simple routes, tuples (regex, 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.

add(route)

Adds a route to this router.

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

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.

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.

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_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.

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.

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.

route_class

Class used when the route is set as a tuple.

alias of SimpleRoute

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.

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_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.

class webapp2.BaseRoute(template, handler=None, name=None, build_only=False)

Interface for URI routes.

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.

build_only = False

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

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.

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_routes()

Generator to get all routes from a route.

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

handler = None

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

handler_adapter = None

The handler, imported and ready for dispatching.

handler_method = None

The custom handler method, if handler is a class.

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.

name = None

Route name, used to build URIs.

template = None

The regex template.

class webapp2.SimpleRoute(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.

__init__(template, handler=None, name=None, build_only=False)

Initializes this route.

Parameters:

• template – A regex to be matched.
• handler – A callable or string in dotted notation to be lazily imported, e.g., 'my.module.MyHandler' or 'my.module.my_function'.
• name – The name of this route, used to build URIs based on it.
• build_only – If True, this route never matches and is used only to build URIs.

match(request)

Matches this route against the current request.

See also

BaseRoute.match().

class webapp2.Route(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.

__init__(template, handler=None, name=None, defaults=None, build_only=False, handler_method=None, methods=None, schemes=None)

Initializes this route.

Parameters:

• template –

  A route template to match against the request path. A template can have variables enclosed by <> that define a name, a regular expression or both. Examples:

  Format	Example
  <name>	'/blog/<year>/<month>'
  <:regex>	'/blog/<:\d{4}>/<:\d{2}>'
  <name:regex>	'/blog/<year:\d{4}>/<month:\d{2}>'

  The same template can mix parts with name, regular expression or both.

  If the name is set, the value of the matched regular expression is passed as keyword argument to the handler. Otherwise it is passed as positional argument.

  If only the name is set, it will match anything except a slash. So these routes are equivalent:

  Route('/<user_id>/settings', handler=SettingsHandler,
        name='user-settings')
  Route('/<user_id:[^/]+>/settings', handler=SettingsHandler,
        name='user-settings')
  

  Note

  The handler only receives *args if no named variables are set. Otherwise, the handler only receives **kwargs. This allows you to set regular expressions that are not captured: just mix named and unnamed variables and the handler will only receive the named ones.

• handler – A callable or string in dotted notation to be lazily imported, e.g., 'my.module.MyHandler' or 'my.module.my_function'. It is possible to define a method if the callable is a class, separating it by a colon: 'my.module.MyHandler:my_method'. This is a shortcut and has the same effect as defining the handler_method parameter.
• name – The name of this route, used to build URIs based on it.
• defaults – Default or extra keywords to be returned by this route. Values also present in the route variables are used to build the URI when they are missing.
• build_only – If True, this route never matches and is used only to build URIs.
• handler_method – The name of a custom handler method to be called, in case handler is a class. If not defined, the default behavior is to call the handler method correspondent to the HTTP request method in lower case (e.g., get(), post() etc).
• methods – A sequence of HTTP methods. If set, the route will only match if the request method is allowed.
• schemes – A sequence of URI schemes, e.g., ['http'] or ['https']. If set, the route will only match requests with these schemes.

build(request, args, kwargs)

Returns a URI for this route.

See also

Router.build().

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().

Configuration

See also

Config

class webapp2.Config(defaults=None)

A simple configuration dictionary for the WSGIApplication.

load_config(key, default_values=None, user_values=None, required_keys=None)

Returns a configuration for a given key.

This can be used by objects that define a default configuration. It will update the app configuration with the default values the first time it is requested, and mark the key as loaded.

Parameters:

• key – A configuration key.
• default_values – Default values defined by a module or class.
• user_values – User values, used when an object can be initialized with configuration. This overrides the app configuration.
• required_keys – Keys that can not be None.

Raises:

Exception, when a required key is not set or is None.

Request and Response

See also

Request data and Building a Response

class webapp2.Request(environ, *args, **kwargs)

Abstraction for an HTTP request.

Most extra methods and attributes are ported from webapp. Check the WebOb documentation for the ones not listed here.

__init__(environ, *args, **kwargs)

Constructs a Request object from a WSGI environment.

Parameters:environ – A WSGI-compliant environment dictionary.

app = None

A reference to the active WSGIApplication instance.

arguments()

Returns a list of the arguments provided in the query and/or POST.

The return value is an ordered list of strings.

get(argument_name, default_value='', allow_multiple=False)

Returns the query or POST argument with the given name.

We parse the query string and POST payload lazily, so this will be a slower operation on the first call.

Parameters:

• argument_name – The name of the query or POST argument.
• default_value – The value to return if the given argument is not present.
• allow_multiple – Return a list of values with the given name (deprecated).

Returns:

Return the value with the given name given in the request. If there are multiple values, this will only return the first one. Use get_all() to get multiple values.

get_all(argument_name, default_value=None)

Returns a list of query or POST arguments with the given name.

We parse the query string and POST payload lazily, so this will be a slower operation on the first call.

Parameters:

• argument_name – The name of the query or POST argument.
• default_value – The value to return if the given argument is not present, None may not be used as a default, if it is then an empty list will be returned instead.

Returns:

A (possibly empty) list of values.

get_range(name, min_value=None, max_value=None, default=0)

Parses the given int argument, limiting it to the given range.

Parameters:

• name – The name of the argument.
• min_value – The minimum int value of the argument (if any).
• max_value – The maximum int value of the argument (if any).
• default – The default value of the argument if it is not given.

Returns:

An int within the given range for the argument.

registry = None

A dictionary to register objects used during the request lifetime.

response = None

A reference to the active Response instance.

route = None

A reference to the matched Route.

route_args = None

The matched route positional arguments.

route_kwargs = None

The matched route keyword arguments.

class webapp2.Response(*args, **kwargs)

Abstraction for an HTTP response.

Most extra methods and attributes are ported from webapp. Check the WebOb documentation for the ones not listed here.

Differences from webapp.Response:

• out is not a StringIO.StringIO instance. Instead it is the response itself, as it has the method write().
• As in WebOb, status is the code plus message, e.g., ‘200 OK’, while in webapp it is the integer code. The status code as an integer is available in status_int, and the status message is available in status_message.
• response.headers raises an exception when a key that doesn’t exist is accessed or deleted, differently from wsgiref.headers.Headers.

__init__(*args, **kwargs)

Constructs a response with the default settings.

clear()

Clears all data written to the output stream so that it is empty.

has_error()

Indicates whether the response was an error response.

static http_status_message(code)

Returns the default HTTP status message for the given code.

Parameters:code – The HTTP code for which we want a message.

status

The status string, including code and message.

status_message

The response status message, as a string.

wsgi_write(start_response)

Writes this response using the given WSGI function.

This is only here for compatibility with webapp.WSGIApplication.

Parameters:start_response – The WSGI-compatible start_response function.

Request handlers

See also

Request handlers

class webapp2.RequestHandler(request=None, response=None)

Base HTTP request handler.

Implements most of webapp.RequestHandler interface.

__init__(request=None, response=None)

Initializes this request handler with the given WSGI application, Request and Response.

When instantiated by webapp.WSGIApplication, request and response are not set on instantiation. Instead, initialize() is called right after the handler is created to set them.

Also in webapp dispatching is done by the WSGI app, while webapp2 does it here to allow more flexibility in extended classes: handlers can wrap dispatch() to check for conditions before executing the requested method and/or post-process the response.

Note

Parameters are optional only to support webapp’s constructor which doesn’t take any arguments. Consider them as required.

Parameters:

• request – A Request instance.
• response – A Response instance.

abort(code, *args, **kwargs)

Raises an HTTPException.

This stops code execution, leaving the HTTP exception to be handled by an exception handler.

Parameters:

• code – HTTP status code (e.g., 404).
• args – Positional arguments to be passed to the exception class.
• kwargs – Keyword arguments to be passed to the exception class.

app = None

A WSGIApplication instance.

dispatch()

Dispatches the request.

This will first check if there’s a handler_method defined in the matched route, and if not it’ll use the method correspondent to the request method (get(), post() etc).

error(code)

Clears the response and sets the given HTTP status code.

This doesn’t stop code execution; for this, use abort().

Parameters:code – HTTP status error code (e.g., 501).

handle_exception(exception, debug)

Called if this handler throws an exception during execution.

The default behavior is to re-raise the exception to be handled by WSGIApplication.handle_exception().

Parameters:

• exception – The exception that was thrown.
• debug_mode – True if the web application is running in debug mode.

initialize(request, response)

Initializes this request handler with the given WSGI application, Request and Response.

Parameters:

• request – A Request instance.
• response – A Response instance.

redirect(uri, permanent=False, abort=False, code=None, body=None)

Issues an HTTP redirect to the given relative URI.

The arguments are described in redirect().

redirect_to(_name, _permanent=False, _abort=False, _code=None, _body=None, *args, **kwargs)

Convenience method mixing redirect() and uri_for().

The arguments are described in redirect() and uri_for().

request = None

A Request instance.

response = None

A Response instance.

uri_for(_name, *args, **kwargs)

Returns a URI for a named Route.

See also

Router.build().

class webapp2.RedirectHandler(request=None, response=None)

Redirects to the given URI for all GET requests.

This is intended to be used when defining URI routes. You must provide at least the keyword argument url in the route default values. Example:

def get_redirect_url(handler, *args, **kwargs):
    return handler.uri_for('new-route-name')

app = WSGIApplication([
    Route('/old-url', RedirectHandler, defaults={'_uri': '/new-url'}),
    Route('/other-old-url', RedirectHandler, defaults={
          '_uri': get_redirect_url}),
])

Based on idea from Tornado.

get(*args, **kwargs)

Performs a redirect.

Two keyword arguments can be passed through the URI route:

• _uri: A URI string or a callable that returns a URI. The callable is called passing (handler, *args, **kwargs) as arguments.
• _code: The redirect status code. Default is 301 (permanent redirect).

Utilities

These are some other utilities also available for general use.

class webapp2.cached_property(func, name=None, doc=None)

A decorator that converts a function into a lazy property.

The function wrapped is called the first time to retrieve the result and then that calculated result is used the next time you access the value:

class Foo(object):

    @cached_property
    def foo(self):
        # calculate something important here
        return 42

The class has to have a __dict__ in order for this property to work.

Note

Implementation detail: this property is implemented as non-data descriptor. non-data descriptors are only invoked if there is no entry with the same name in the instance’s __dict__. this allows us to completely get rid of the access function call overhead. If one choses to invoke __get__ by hand the property will still work as expected because the lookup logic is replicated in __get__ for manual invocation.

This class was ported from Werkzeug and Flask.

webapp2.get_app()

Returns the active app instance.

Returns:A WSGIApplication instance.

webapp2.get_request()

Returns the active request instance.

Returns:A Request instance.

webapp2.redirect(uri, permanent=False, abort=False, code=None, body=None, request=None, response=None)

Issues an HTTP redirect to the given relative URI.

This won’t stop code execution unless abort is True. A common practice is to return when calling this method:

return redirect('/some-path')

Parameters:

• uri – A relative or absolute URI (e.g., '../flowers.html').
• permanent – If True, uses a 301 redirect instead of a 302 redirect.
• abort – If True, raises an exception to perform the redirect.
• code – The redirect status code. Supported codes are 301, 302, 303, 305, and 307. 300 is not supported because it’s not a real redirect and 304 because it’s the answer for a request with defined If-Modified-Since headers.
• body – Response body, if any.
• request – Optional request object. If not set, uses get_request().
• response – Optional response object. If not set, a new response is created.

Returns:

A Response instance.

webapp2.redirect_to(_name, _permanent=False, _abort=False, _code=None, _body=None, _request=None, _response=None, *args, **kwargs)

Convenience function mixing redirect() and uri_for().

Issues an HTTP redirect to a named URI built using uri_for().

Parameters:

• _name – The route name to redirect to.
• args – Positional arguments to build the URI.
• kwargs – Keyword arguments to build the URI.

Returns:

A Response instance.

The other arguments are described in redirect().

webapp2.uri_for(_name, _request=None, *args, **kwargs)

A standalone uri_for version that can be passed to templates.

See also

Router.build().

webapp2.abort(code, *args, **kwargs)

Raises an HTTPException.

Parameters:

• code – An integer that represents a valid HTTP status code.
• args – Positional arguments to instantiate the exception.
• kwargs – Keyword arguments to instantiate the exception.

webapp2.import_string(import_name, silent=False)

Imports an object based on a string in dotted notation.

Simplified version of the function with same name from Werkzeug.

Parameters:

• import_name – String in dotted notation of the object to be imported.
• silent – If True, import or attribute errors are ignored and None is returned instead of raising an exception.

Returns:

The imported object.