From 06e6c078a48449019d87b86f0d138bcb54df3139 Mon Sep 17 00:00:00 2001 From: Ben Darnell Date: Thu, 28 Mar 2013 00:11:06 -0400 Subject: [PATCH] Replace the outdated README.md with a lightly-edited version of docs/index.rst --- README.md | 56 -------------------------- README.rst | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 116 insertions(+), 56 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/README.md b/README.md deleted file mode 100644 index 2cdb05a7d..000000000 --- a/README.md +++ /dev/null @@ -1,56 +0,0 @@ -Tornado -======= -Tornado is an open source version of the scalable, non-blocking web server -and and tools that power FriendFeed. Documentation and downloads are -available at http://www.tornadoweb.org/ - -Tornado is licensed under the Apache Licence, Version 2.0 -(http://www.apache.org/licenses/LICENSE-2.0.html). - -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. - -Manual installation -------------------- - -Download the latest release from http://pypi.python.org/pypi/tornado - - tar xvzf tornado-$VERSION.tar.gz - cd tornado-$VERSION - python setup.py build - sudo python setup.py install - -The Tornado source code is hosted on GitHub: https://github.com/facebook/tornado - -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.6+ and 3.2+. Both CPython and PyPy are supported. - -There are no required dependencies outside the Python standard library, -although unittest2 is required to run Tornado's unittest suite on -Python 2.6. - -Certain optional features require additional third-party modules: - -* tornado.curl_httpclient needs PycURL (version 7.18.2 or higher required; - version 7.21.1 or higher recommended) -* Multithreading support requires the concurrent.futures module, - which is in the standard library for Python 3.2+ and available - at http://pypi.python.org/pypi/futures for older versions. - -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. diff --git a/README.rst b/README.rst new file mode 100644 index 000000000..7302df9b5 --- /dev/null +++ b/README.rst @@ -0,0 +1,116 @@ +Tornado Web Server +================== + +`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 +----------- + +* :doc:`Documentation `_ +* `Source (github) `_ +* `Mailing list `_ +* `Wiki `_ + +Hello, world +------------ + +Here is a simple "Hello, world" example web app for Tornado:: + + import tornado.ioloop + import tornado.web + + class MainHandler(tornado.web.RequestHandler): + def get(self): + self.write("Hello, world") + + application = tornado.web.Application([ + (r"/", MainHandler), + ]) + + if __name__ == "__main__": + application.listen(8888) + tornado.ioloop.IOLoop.instance().start() + +This example does not use any of Tornado's asynchronous features; for +that see this `simple chat room +`_. + +Installation +------------ + +**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 the latest source from `PyPI +`_. + +.. parsed-literal:: + + tar xvzf tornado-$VERSION.tar.gz + cd tornado-$VERSION + python setup.py build + sudo python setup.py install + +The Tornado source code is `hosted on GitHub +`_. + +**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 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 +`_. It is available under +the `Apache License, Version 2.0 +`_. + +This web site and all documentation is licensed under `Creative +Commons 3.0 `_. -- 2.47.2