From: Ben Darnell Date: Mon, 11 Mar 2013 03:04:06 +0000 (-0400) Subject: Rewrite text on index page. X-Git-Tag: v3.0.0~38 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=16932d8cff5c513fa723d66b6a37181beddd3578;p=thirdparty%2Ftornado.git Rewrite text on index page. --- diff --git a/docs/index.rst b/docs/index.rst index 3e41d584e..11477fc9d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,35 +6,14 @@ .. |Tornado Web Server| image:: tornado.png :alt: Tornado Web Server -`Tornado `_ is an open source version of -the scalable, non-blocking web server and tools that power `FriendFeed -`_. The FriendFeed application is written -using a web framework that looks a bit like `web.py -`_ or `Google's webapp -`_, but -with additional tools and optimizations to take advantage of the -underlying non-blocking infrastructure. - -The framework is distinct from most mainstream web server frameworks -(and certainly most Python frameworks) because it is non-blocking and -reasonably fast. Because it is non-blocking and uses `epoll -`_ -or ``kqueue``, it can handle thousands of simultaneous standing -connections, which means it is ideal for real-time web services. We -built the web server specifically to handle FriendFeed's real-time -features — every active user of FriendFeed maintains an open -connection to the FriendFeed servers. (For more information on scaling -servers to support thousands of clients, see The `C10K problem -`_.) - -Upgrading from Tornado 1.x --------------------------- - -Tornado 2.0 introduces several potentially backwards-incompatible -changes, including in particular automatic escaping of template -output. Users who are upgrading from Tornado 1.x should see the -:doc:`version 2.0 release notes ` for -information about backwards compatibility. +`Tornado `_ is a Python web framework and +asynchronous networking library, originally developed at `FriendFeed +`_. By using non-blocking network I/O, Tornado +can scale to tens of thousands of open connections, making it ideal for +`long polling `_, +`WebSockets `_, and other +applications that require a long-lived connection to each user. + Quick links ----------- @@ -50,7 +29,7 @@ Quick links Hello, world ------------ -Here is the canonical "Hello, world" example app for Tornado:: +Here is a simple "Hello, world" example web app for Tornado:: import tornado.ioloop import tornado.web @@ -65,22 +44,26 @@ Here is the canonical "Hello, world" example app for Tornado:: if __name__ == "__main__": application.listen(8888) - tornado.ioloop.IOLoop.instance().start() + tornado.ioloop.IOLoop.instance().start() -See the :doc:`Tornado documentation ` for a -detailed walkthrough of the framework. +This example does not use any of Tornado's asynchronous features; for +that see this `simple chat room +`_. Installation ------------ -**Automatic installation:** Tornado is listed in `PyPI -`_ and can be installed with -``pip`` or ``easy_install``. Note that the source distribution -includes demo applications that are not present when Tornado is -installed in this way, so you may wish to download a copy of the -source tarball as well. +**Automatic installation**:: + + pip install tornado + +Tornado is listed in `PyPI `_ and +can be installed with ``pip`` or ``easy_install``. Note that the +source distribution includes demo applications that are not present +when Tornado is installed in this way, so you may wish to download a +copy of the source tarball as well. -**Manual installation:** Download :current_tarball:`z`: +**Manual installation**: Download :current_tarball:`z`: .. parsed-literal:: @@ -90,36 +73,45 @@ source tarball as well. sudo python setup.py install The Tornado source code is `hosted on GitHub -`_. On Python 2.6 and 2.7, it is -also possible to simply add the tornado directory to your -``PYTHONPATH`` instead of building with ``setup.py``, since the -standard library includes ``epoll`` support. - -**Prerequisites:** Tornado runs on Python 2.5, 2.6, 2.7 and 3.2. - -* On Python 2.6 and 2.7, there are no dependencies outside the Python - standard library, although `PycURL - `_ (version 7.18.2 or higher - required; version 7.21.1 or higher recommended) may be used if - desired. -* On Python 2.5, PycURL is required, along with `simplejson - `_ and the Python - development headers (typically obtained by installing a package - named something like ``python-dev`` from your operating system). -* On Python 3.2, the `distribute - `_ package is required. - Note that Python 3 support is relatively new and may have bugs. - -**Platforms:** Tornado should run on any Unix-like platform, although -for the best performance and scalability only Linux and BSD (including -BSD derivatives like Mac OS X) are recommended. +`_. + +**Prerequisites**: Tornado runs on Python 2.6, 2.7, 3.2, and 3.3. It has +no strict dependencies outside the Python standard library, although some +features may require one of the following libraries: + +* `unittest2 `_ is needed to run + Tornado's test suite on Python 2.6 (it is unnecessary on more recent + versions of Python) +* `concurrent.futures `_ is the + recommended thread pool for use with Tornado and enables the use of + `~tornado.netutil.ThreadedResolver`. It is needed only on Python 2; + Python 3 includes this package in the standard library. +* `pycurl `_ is used by the optional + `tornado.curl_httpclient`. Libcurl version 7.18.2 or higher is required; + version 7.21.1 or higher is recommended. +* `Twisted `_ may be used with the classes in + `tornado.platform.twisted`. +* `pycares `_ is an alternative + non-blocking DNS resolver that can be used when threads are not + appropriate. +* `Monotime `_ adds support for + a monotonic clock, which improves reliability in environments + where clock adjustments are frequent. No longer needed in Python 3.3. + +**Platforms**: Tornado should run on any Unix-like platform, although +for the best performance and scalability only Linux (with ``epoll``) +and BSD (with ``kqueue``) are recommended (even though Mac OS X is +derived from BSD and supports kqueue, its networking performance is +generally poor so it is recommended only for development use). Discussion and support ---------------------- -You can discuss Tornado and report bugs on `the Tornado developer -mailing list `_. Links -to additional resources can be found on the `Tornado wiki +You can discuss Tornado on `the Tornado developer mailing list +`_, and report bugs on +the `GitHub issue trackier +`_. Links to additional +resources can be found on the `Tornado wiki `_. Tornado is one of `Facebook's open source technologies