Add convenience method Application.listen(port) so most apps don't need

to explicitly touch HTTPServer.

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

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.
 

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

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>