From: Ben Darnell <ben@bendarnell.com>
Date: Tue, 16 Nov 2010 05:15:32 +0000 (-0800)
Subject: Add convenience method Application.listen(port) so most apps don't need
X-Git-Tag: v1.2.0~74
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a853850e26d31288941a264125b674d9def9f096;p=thirdparty%2Ftornado.git

Add convenience method Application.listen(port) so most apps don't need
to explicitly touch HTTPServer.
---

diff --git a/demos/chat/chatdemo.py b/demos/chat/chatdemo.py
index 7086592ec..8a1cab565 100755
--- a/demos/chat/chatdemo.py
+++ b/demos/chat/chatdemo.py
@@ -131,7 +131,7 @@ class AuthLoginHandler(BaseHandler, tornado.auth.GoogleMixin):
             self.get_authenticated_user(self.async_callback(self._on_auth))
             return
         self.authenticate_redirect(ax_attrs=["name"])
-    
+
     def _on_auth(self, user):
         if not user:
             raise tornado.web.HTTPError(500, "Google auth failed")
@@ -147,8 +147,8 @@ class AuthLogoutHandler(BaseHandler):
 
 def main():
     tornado.options.parse_command_line()
-    http_server = tornado.httpserver.HTTPServer(Application())
-    http_server.listen(options.port)
+    app = Application()
+    app.listen(options.port)
     tornado.ioloop.IOLoop.instance().start()
 
 
diff --git a/tornado/web.py b/tornado/web.py
index 83521ace0..beb1457c1 100644
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -23,7 +23,6 @@ Tornado non-blocking web server and tools.
 
 Here is the canonical "Hello, world" example app:
 
-    import tornado.httpserver
     import tornado.ioloop
     import tornado.web
 
@@ -35,12 +34,11 @@ Here is the canonical "Hello, world" example app:
         application = tornado.web.Application([
             (r"/", MainHandler),
         ])
-        http_server = tornado.httpserver.HTTPServer(application)
-        http_server.listen(8888)
+        application.listen(8888)
         tornado.ioloop.IOLoop.instance().start()
 
-See the Tornado walkthrough on GitHub for more details and a good
-getting started guide.
+See the Tornado walkthrough on http://tornadoweb.org for more details
+and a good getting started guide.
 """
 
 from __future__ import with_statement
@@ -1029,6 +1027,24 @@ class Application(object):
             import autoreload
             autoreload.start()
 
+    def listen(self, port, **kwargs):
+        """Starts an HTTP server for this application on the given port.
+
+        This is a convenience alias for creating an HTTPServer object
+        and calling its listen method.  Keyword arguments are passed to
+        the HTTPServer constructor.  For advanced uses (e.g. preforking),
+        do not use this method; create an HTTPServer and call its
+        bind/start methods directly.
+
+        Note that after calling this method you still need to call
+        IOLoop.instance().start() to start the server.
+        """
+        # import is here rather than top level because HTTPServer
+        # is not importable on appengine
+        from tornado.httpserver import HTTPServer
+        server = HTTPServer(self, **kwargs)
+        server.listen(port)
+
     def add_handlers(self, host_pattern, host_handlers):
         """Appends the given handlers to our handler list.
 
diff --git a/website/templates/documentation.txt b/website/templates/documentation.txt
index 308412bf1..4ea3887d6 100644
--- a/website/templates/documentation.txt
+++ b/website/templates/documentation.txt
@@ -23,7 +23,6 @@ thousands of clients, see
 
 Here is the canonical "Hello, world" example app:
 
-    import tornado.httpserver
     import tornado.ioloop
     import tornado.web
 
@@ -36,8 +35,7 @@ Here is the canonical "Hello, world" example app:
     ])
 
     if __name__ == "__main__":
-        http_server = tornado.httpserver.HTTPServer(application)
-        http_server.listen(8888)
+        application.listen(8888)
         tornado.ioloop.IOLoop.instance().start()
 
 See [Tornado walkthrough](#tornado-walkthrough) below for a detailed
diff --git a/website/templates/index.html b/website/templates/index.html
index a4e647acf..92c31b78e 100644
--- a/website/templates/index.html
+++ b/website/templates/index.html
@@ -26,8 +26,7 @@ sudo python setup.py install</code></pre>
 
   <h2>Hello, world</h2>
   <p>Here is the canonical &quot;Hello, world&quot; example app for Tornado:</p>
-  <pre><code>import tornado.httpserver
-import tornado.ioloop
+  <pre><code>import tornado.ioloop
 import tornado.web
 
 class MainHandler(tornado.web.RequestHandler):
@@ -39,8 +38,7 @@ application = tornado.web.Application([
 ])
 
 if __name__ == "__main__":
-    http_server = tornado.httpserver.HTTPServer(application)
-    http_server.listen(8888)
+    application.listen(8888)
     tornado.ioloop.IOLoop.instance().start()</code></pre>
   <p>See the <a href="/documentation">Tornado documentation</a> for a detailed walkthrough of the framework.</p>