Version 0.2 (#84)

* First pass at version 0.2

* Add click to requirements

* Add RequestResponseCycle

* Checks around request/response state

* Building out tests with starlette. Lots of improved error handling.

* Run tests against both H11Protocol and HttpToolsProtocol

* HTTP 1.0 test case

* WebSocket support re-introduced for httptools

* Add server: and date: headers

* Black formatting

* Fix logging with gunicorn

* Move worker class, add run() function.

* Update docs, and include markdown on pypi

* Include py3.7-dev in travis matrix

* Drop 3.7-dev due to apparent issues with async generators

* Comment out streaming test to check if async generators error still raised

* Bump to 3.6 temporarily.

* Drop hanging websocket tests temporarily

* Rework tests to not require py3.6+

* Use __slots__

* Minor tweak on logging for consistency

* Track total_requests

* Default to port 8000

* Uncomment websocket tests that don't appear to hang

* See if thread.join() resolves hanging on travis

* Downgrade websockets version

docs/index.md

@@ -49,6 +49,66 @@ Run the server:
 $ uvicorn app:App
 ```
 
+# Usage
+
+The uvicorn command line tool is the easiest way to run your application...
+
+## Command line options
+
+```shell
+Usage: uvicorn [OPTIONS] APP
+
+Options:
+  --host TEXT                     Host
+  --port INTEGER                  Port
+  --loop [uvloop|asyncio]         Event loop
+  --http [httptools|h11]          HTTP Handler
+  --workers INTEGER               Number of worker processes
+  --log-level [debug|info|warning|error|critical]
+                                  Log level
+  --help                          Show this message and exit.
+```
+
+Uvicorn currently includes two HTTP implementations, "httptools" and "h11".
+
+It also supports two different event loop implementations, "uvloop" and
+Python's standard "asyncio".
+
+The default configuration is to use httptools and uvloop. If you need to
+run under [PyPy][pypy], then you should switch to h11 and asyncio.
+
+## Running programmatically
+
+To run uvicorn directly from your application...
+
+```python
+import uvicorn
+
+...
+
+if __name__ == "__main__":
+    uvicorn.run("127.0.0.1", 5000, log_level="info")
+```
+
+## Running with Gunicorn
+
+[Gunicorn][gunicorn] is a mature, fully featured server and process manager.
+
+Uvicorn includes a Gunicorn worker class allowing you to run ASGI applications,
+with all of Uvicorn's performance benefits, while also giving you Gunicorn's
+fully-featured process management.
+
+This allows you to increase or decrease the number of worker processes on the
+fly, restart worker processes gracefully, or perform server upgrades without downtime.
+
+For production deployments we recommend using gunicorn with the uvicorn worker class.
+
+```
+gunicorn app:App -w 4 -k uvicorn.workers.UvicornWorker
+```
+
+For a [PyPy][pypy] compatible configuration use `uvicorn.workers.UvicornH11Worker`.
+
 # The ASGI interface
 
 Uvicorn uses the [ASGI specification][asgi] for interacting with an application.
@@ -215,6 +275,8 @@ class StreamResponse():
 
 # Alternative ASGI servers
 
+## Daphne
+
 The first ASGI server implementation, originally developed to power Django Channels,
 is [the Daphne webserver][daphne].
 
@@ -227,8 +289,21 @@ $ pip install daphne
 $ daphne app:App
 ```
 
+## Hypercorn
+
+[Hypercorn][hypercorn] was initially part of the Quart web framework, before
+being separated out into a standalone ASGI server.
+
+```shell
+$ pip install hypercorn
+$ hypercorn app:App
+```
+
 [uvloop]: https://github.com/MagicStack/uvloop
 [httptools]: https://github.com/MagicStack/httptools
-[asgi]: https://github.com/django/asgiref/blob/master/specs/asgi.rst
-[asgi-http]: https://github.com/django/asgiref/blob/master/specs/www.rst
+[gunicorn]: http://gunicorn.org/
+[pypy]: https://pypy.org/
+[asgi]: https://asgi.readthedocs.io/en/latest/
+[asgi-http]: https://asgi.readthedocs.io/en/latest/specs/www.html
 [daphne]: https://github.com/django/daphne
+[hypercorn]: https://gitlab.com/pgjones/hypercorn

requirements.txt

@@ -1,7 +1,8 @@
-gunicorn
+click
+h11
 httptools
 uvloop
-websockets
+websockets==3.3
 
 # Testing
 pytest

setup.py

@@ -7,8 +7,6 @@
 
 from setuptools import setup
 
-sys.dont_write_bytecode = True
-
 
 def get_version(package):
     """
@@ -18,6 +16,13 @@ def get_version(package):
     return re.search("__version__ = ['\"]([^'\"]+)['\"]", init_py).group(1)
 
 
+def get_long_description():
+    """
+    Return the README.
+    """
+    return open('README.md', 'r').read()
+
+
 def get_packages(package):
     """
     Return root package and all sub-packages.
@@ -35,15 +40,18 @@ def get_packages(package):
     version=version,
     url='https://github.com/tomchristie/uvicorn',
     license='BSD',
-    description='An ASGI server, using Gunicorn and uvloop.',
+    description='The lightning-fast asyncio server.',
+    long_description=get_long_description(),
+    long_description_content_type='text/markdown',
     author='Tom Christie',
     author_email='tom@tomchristie.com',
     packages=get_packages('uvicorn'),
     install_requires=[
-        'gunicorn',
+        'click',
+        'h11',
         'httptools',
         'uvloop',
-        'websockets'
+        'websockets==3.3'
     ],
     classifiers=[
         'Development Status :: 3 - Alpha',
@@ -55,9 +63,10 @@ def get_packages(package):
         'Programming Language :: Python :: 3',
         'Programming Language :: Python :: 3.5',
         'Programming Language :: Python :: 3.6',
+        'Programming Language :: Python :: 3.7',
     ],
     entry_points="""
     [console_scripts]
-    uvicorn=uvicorn.main:run
+    uvicorn=uvicorn.main:main
     """
 )