#!/usr/bin/env python # -*- coding: utf-8 -*- # # Copyright 2009 Dan McDougall # # Licensed under the Apache License, Version 2.0 (the "License"); you may # not use this file except in compliance with the License. You may obtain # a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the # License for the specific language governing permissions and limitations # under the License. # Meta __version__ = '1.0' __license__ = "Apache License, Version 2.0" __version_info__ = (1, 0) __author__ = 'Dan McDougall ' """ Tornado MethodDispatcher ======================== The MethodDispatcher is a subclass of tornado.web.RequestHandler that will use the methods contained in subclasses of MethodDispatcher to handle requests. In other words, instead of having to make a new RequestHandler class for every URL in your application you can subclass MethodDispatcher and use the methods contained therein *as* your URLs. The MethodDispatcher also adds the convenience of automatically passing arguments to your class methods. So there is no need to use Tornado's get_argument() method. Example ------- To demonstrate the advantages of using MethodDispatcher I'll present a standard Tornado app with multiple URLs and re-write it using MethodDispatcher... The standard Tornado way ------------------------ class Foo(tornado.web.RequestHandler): def get(self): self.write('foo') class Bar(tornado.web.RequestHandler): def get(self): self.write('bar') class SimonSays(tornado.web.RequestHandler): def get(self): say = self.get_argument("say") self.write('Simon says, %s' % `say`) application = tornado.web.Application([ (r"/foo", Foo), (r"/bar", Bar), (r"/simonsays", SimonSays), ]) The MethodDispatcher way ------------------------ class FooBar(MethodDispatcher): def foo(self): self.write("foo") def bar(self): self.write("bar") def simonsays(self, say): self.write("Simon Says, %s" % `say`) application = tornado.web.Application([ (r"/.*", FooBar) ]) Notes ----- As you can see from the above example, using the MethodDispatcher can significantly reduce the complexity of Tornado applications. Here's some other things to keep in mind when using the MethodDispatcher: * MethodDispatcher will ignore any methods that begin with an underscore (_). This prevents builtins and private methods from being exposed to the web. * The '/' path is special: It always maps to self.index(). * MethodDispatcher does not require that your methods distinquish between GET and POST requests. Whether a GET or POST is performed the matching method will be called with any passed arguments or POSTed data. Because of the way this works you should not use get() and post() in your MethodDispatcher subclasses unless you want to override this functionality. * When an argument is passed with a single value (/simonsays?say=hello) the value passed to the argument will be de-listed. In other words, it will be passed to your method like so: {'say': 'hello'}. This overrides the default Tornado behavior which would return the value as a list: {'say': ['hello']}. If more than one value is passed MethodDispatcher will use the default behavior. """ import tornado.web def delist_arguments(args): """ Takes a dictionary, 'args' and de-lists any single-item lists then returns the resulting dictionary. In other words, {'foo': ['bar']} would become {'foo': 'bar'} """ for arg, value in args.items(): if len(value) == 1: args[arg] = value[0] return args class MethodDispatcher(tornado.web.RequestHandler): """ Subclasss this to have all of your class's methods exposed to the web for both GET and POST requests. Class methods that start with an underscore (_) will be ignored. """ def _dispatch(self): """ Load up the requested URL if it matches one of our own methods. Skip methods that start with an underscore (_). """ args = None # Sanitize argument lists: if self.request.arguments: args = delist_arguments(self.request.arguments) # Special index method handler: if self.request.uri.endswith('/'): func = getattr(self, 'index', None) if args: return func(**args) else: return func() path = self.request.uri.split('?')[0] method = path.split('/')[-1] if not method.startswith('_'): func = getattr(self, method, None) if func: if args: return func(**args) else: return func() else: raise tornado.web.HTTPError(404) else: raise tornado.web.HTTPError(404) def get(self): """Returns self._dispatch()""" return self._dispatch() def post(self): """Returns self._dispatch()""" return self._dispatch() class TestMethodDispatcher(MethodDispatcher): """ This class demonstrates how to use MethodDispatcher() to load URLs based on the names of the methods in a class. It also demonstrates the special index handler and how arguments are passed to methods. """ def index(self): self.write( "The special index handler has been called.
" "Try " "testing?foo=bar&say=hello" ) def testing(self, **kwargs): self.write("testing() got the following arguments: %s" % `kwargs`) class TestApplication(tornado.web.Application): """ This Tornado Application container demonstrates how to include a MethodDispatcher class in your app via a catch-all regular expression. """ def __init__(self): handlers = [ # Basic catch-all URL handler: (r"/.*", TestMethodDispatcher), # You can also use a MethodDispatcher in sub-paths: (r"/test/.*", TestMethodDispatcher) ] tornado.web.Application.__init__(self, handlers) def test_method_dispatcher(): """ This function can be used to test that the MethodDispatcher is working properly. It is called automatically when this script is executed directly. """ import logging from tornado.ioloop import IOLoop from tornado.httpserver import HTTPServer from tornado.options import define, options, parse_command_line define("port", default=8888, help="Run on the given port", type=int) parse_command_line() logging.info( "Test Server Listening on" % options.port ) http_server = HTTPServer(TestApplication()) http_server.listen(options.port) IOLoop.instance().start() if __name__ == "__main__": test_method_dispatcher()