From a853850e26d31288941a264125b674d9def9f096 Mon Sep 17 00:00:00 2001
From: Ben Darnell <ben@bendarnell.com>
Date: Mon, 15 Nov 2010 21:15:32 -0800
Subject: [PATCH] Add convenience method Application.listen(port) so most apps
 don't need to explicitly touch HTTPServer.

---
 demos/chat/chatdemo.py              |  6 +++---
 tornado/web.py                      | 26 +++++++++++++++++++++-----
 website/templates/documentation.txt |  4 +---
 website/templates/index.html        |  6 ++----
 4 files changed, 27 insertions(+), 15 deletions(-)

diff --git a/demos/chat/chatdemo.py b/demos/chat/chatdemo.py
index 7086592ec4..8a1cab5658 100755
--- a/demos/chat/chatdemo.py
+++ b/demos/chat/chatdemo.py
@@ -131,7 +131,7 @@ def get(self):
             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 @@ def get(self):
 
 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 83521ace01..beb1457c13 100644
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -23,7 +23,6 @@
 
 Here is the canonical "Hello, world" example app:
 
-    import tornado.httpserver
     import tornado.ioloop
     import tornado.web
 
@@ -35,12 +34,11 @@ def get(self):
         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 @@ def __init__(self, handlers=None, default_host="", transforms=None,
             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 308412bf12..4ea3887d64 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 a4e647acf7..92c31b78e2 100644
--- a/website/templates/index.html
+++ b/website/templates/index.html
@@ -26,8 +26,7 @@ <h3>Prerequisites</h3>
 
   <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 @@ <h2>Hello, world</h2>
 ])
 
 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>