Request handlers
In the webapp2 vocabulary, request handler or simply handler is a common term that refers to the callable that contains the application logic to handle a request. This sounds a lot abstract, but we will explain everything in details in this section.
Handlers 101
A handler is equivalent to the Controller in the MVC terminology: in a simplified manner, it is where you process the request, manipulate data and define a response to be returned to the client: HTML, JSON, XML, files or whatever the app requires.
Normally a handler is a class that extends webapp2.RequestHandler or, for compatibility purposes,webapp.RequestHandler. Here is a simple one:
class ProductHandler(webapp2.RequestHandler):
def get(self, product_id):
self.response.write('You requested product %r.' % product_id)
app = webapp2.WSGIApplication([
(r'/products/(d+)', ProductHandler),
])
This code defines one request handler, ProductHandler, and a WSGI application that maps the URIr'/products/(d+)' to that handler. When the application receives an HTTP request to a path that matches this regular expression, it instantiates the handler and calls the corresponding HTTP method from it. The handler above can only handle GET HTTP requests, as it only defines a get() method. To handle POSTrequests, it would need to implement a post() method, and so on.
The handler method receives a product_id extracted from the URI, and sets a simple message containing the id as response. Not very useful, but this is just to show how it works. In a more complete example, the handler would fetch a corresponding record from a database and set an appropriate response – HTML, JSON or XML with details about the requested product, for example.
For more details about how URI variables are defined, see URI routing.
HTTP methods translated to class methods
The default behavior of the webapp2.RequestHandler is to call a method that corresponds with the HTTP action of the request, such as the get() method for a HTTP GET request. The method processes the request and prepares a response, then returns. Finally, the application sends the response to the client.
The following example defines a request handler that responds to HTTP GET requests:
class AddTwoNumbers(webapp2.RequestHandler):
def get(self):
try:
first = int(self.request.get('first'))
second = int(self.request.get('second'))
self.response.write("<html><body><p>%d + %d = %d</p></body></html>" %
(first, second, first + second))
except (TypeError, ValueError):
self.response.write("<html><body><p>Invalid inputs</p></body></html>")
A request handler can define any of the following methods to handle the corresponding HTTP actions:
- get()
- post()
- head()
- options()
- put()
- delete()
- trace()
View functions
In some Python frameworks, handlers are called view functions or simply views. In Django, for example,views are normally simple functions that handle a request. Our examples use mostly classes, but webapp2 handlers can also be normal functions equivalent to Django’s views.
A webapp2 handler can, really, be any callable. The routing system has hooks to adapt how handlers are called, and two default adapters are used whether it is a function or a class. So, differently from webapp, ordinary functions can easily be used to handle requests in webapp2, and not only classes. The following example demonstrates it:
def display_product(request, *args, **kwargs):
return webapp2.Response('You requested product %r.' % args[0])
app = webapp2.WSGIApplication([
(r'/products/(d+)', display_product),
])
Here, our handler is a simple function that receives the request instance, positional route variables as *argsand named variables as **kwargs, if they are defined.
Apps can have mixed handler classes and functions. Also it is possible to implement new interfaces to define how handlers are called: this is done setting new handler adapters in the routing system.
Functions are an alternative for those that prefer their simplicity or think that handlers don’t benefit that much from the power and flexibility provided by classes: inheritance, attributes, grouped methods, descriptors, metaclasses, etc. An app can have mixed handler classes and functions.
Note
We avoid using the term view because it is often confused with the View definition from the classic MVCpattern. Django prefers to call its MVC implementation MTV (model-template-view), so view may make sense in their terminology. Still, we think that the term can cause unnecessary confusion and prefer to usehandler instead, like in other Python frameworks (webapp, web.py or Tornado, for instance). In essence, though, they are synonyms.
Returned values
A handler method doesn’t need to return anything: it can simply write to the response object using self.response.write().
But a handler can return values to be used in the response. Using the default dispatcher implementation, if a handler returns anything that is not None it must be a webapp2.Response instance. If it does so, that response object is used instead of the default one.
For example, let’s return a response object with a Hello, world message:
class HelloHandler(webapp2.RequestHandler):
def get(self):
return webapp2.Response('Hello, world!')
This is the same as:
class HelloHandler(webapp2.RequestHandler):
def get(self):
self.response.write('Hello, world!')
What if you think that returning a response object is verbose, and want to return simple strings? Fortunately webapp2 has all the necessary hooks to make this possible. To achieve it, we need to extend the router dispatcher to build a Response object using the returned string. We can go even further and also accept tuples: if a tuple is returned, we use its values as positional arguments to instantiate the Response object. So let’s define our custom dispatcher and a handler that returns a string:
def custom_dispatcher(router, request, response):
rv = router.default_dispatcher(request, response)
if isinstance(rv, basestring):
rv = webapp2.Response(rv)
elif isinstance(rv, tuple):
rv = webapp2.Response(*rv)
return rv
class HelloHandler(webapp2.RequestHandler):
def get(self, *args, **kwargs):
return 'Hello, world!'
app = webapp2.WSGIApplication([
(r'/', HelloHandler),
])
app.router.set_dispatcher(custom_dispatcher)
And that’s all. Now we have a custom dispatcher set using the router methodwebapp2.Router.set_dispatcher(). Our HelloHandler returns a string (or it could be tuple) that is used to create a Response object.
Our custom dispatcher could implement its own URI matching and handler dispatching mechanisms from scratch, but in this case it just extends the default dispatcher a little bit, wrapping the returned value under certain conditions.
A micro-framework based on webapp2
Following the previous idea of a custom dispatcher, we could go a little further and extend webapp2 to accept routes registered using a decorator, like in those Python micro-frameworks.
Without much ado, ladies and gentlemen, we present micro-webapp2:
import webapp2
class WSGIApplication(webapp2.WSGIApplication):
def __init__(self, *args, **kwargs):
super(WSGIApplication, self).__init__(*args, **kwargs)
self.router.set_dispatcher(self.__class__.custom_dispatcher)
@staticmethod
def custom_dispatcher(router, request, response):
rv = router.default_dispatcher(request, response)
if isinstance(rv, basestring):
rv = webapp2.Response(rv)
elif isinstance(rv, tuple):
rv = webapp2.Response(*rv)
return rv
def route(self, *args, **kwargs):
def wrapper(func):
self.router.add(webapp2.Route(handler=func, *args, **kwargs))
return func
return wrapper
Save the above code as micro_webapp2.py. Then you can import it in main.py and define your handlers and routes like this:
import micro_webapp2
app = micro_webapp2.WSGIApplication()
@app.route('/')
def hello_handler(request, *args, **kwargs):
return 'Hello, world!'
def main():
app.run()
if __name__ == '__main__':
main()
This example just demonstrates some of the power and flexibility that lies behind webapp2; explore thewebapp2 API to discover other ways to modify or extend the application behavior.
Overriding __init__()
If you want to override the webapp2.RequestHandler.__init__() method, you must callwebapp2.RequestHandler.initialize() at the beginning of the method. It’ll set the current request, response and app objects as attributes of the handler. For example:
class MyHandler(webapp2.RequestHandler):
def __init__(self, request, response):
# Set self.request, self.response and self.app.
self.initialize(request, response)
# ... add your custom initializations here ...
# ...
Overriding dispatch()
One of the advantadges of webapp2 over webapp is that you can wrap the dispatching process ofwebapp2.RequestHandler to perform actions before and/or after the requested method is dispatched. You can do this overriding the webapp2.RequestHandler.dispatch() method. This can be useful, for example, to test if requirements were met before actually dispatching the requested method, or to perform actions in the response object after the method was dispatched. Here’s an example:
class MyHandler(webapp2.RequestHandler):
def dispatch(self):
# ... check if requirements were met ...
# ...
if requirements_were_met:
# Parent class will call the method to be dispatched
# -- get() or post() or etc.
super(MyHandler, self).dispatch()
else:
self.abort(403)
In this case, if the requirements were not met, the method won’t ever be dispatched and a “403 Forbidden” response will be returned instead.
There are several possibilities to explore overriding dispatch(), like performing common checkings, setting common attributes or post-processing the response.