Deprecate gaiohttp worker and document alternatives (benoitc#1569)

Fixes benoitc#1338

docs/source/design.rst

@@ -53,6 +53,9 @@ There's also a Tornado worker class. It can be used to write applications using
 the Tornado framework. Although the Tornado workers are capable of serving a
 WSGI application, this is not a recommended configuration.
 
+
+.. _asyncio-workers:
+
 AsyncIO Workers
 ---------------
 
@@ -66,6 +69,23 @@ the connection is closed.
 
 The worker `gaiohttp` is a full asyncio worker using aiohttp_.
 
+.. note::
+   The ``gaiohttp`` worker requires the aiohttp_ module to be installed.
+   aiohttp_ has removed its native WSGI application support in version 2.
+   If you want to continue to use the ``gaiohttp`` worker with your WSGI
+   application (e.g. an application that uses Flask or Django), there are
+   three options available:
+
+   #. Install aiohttp_ version 1.3.5 instead of version 2::
+
+        $ pip install aiohttp==1.3.5
+
+   #. Use aiohttp_wsgi_ to wrap your WSGI application. You can take a look
+      at the `example`_ in the Gunicorn repository.
+   #. Port your application to use aiohttp_'s ``web.Application`` API.
+   #. Use the ``aiohttp.worker.GunicornWebWorker`` worker instead of the
+      deprecated ``gaiohttp`` worker.
+
 Choosing a Worker Type
 ======================
 
@@ -137,4 +157,6 @@ code in the master process).
 .. _Eventlet: http://eventlet.net/
 .. _Gevent: http://www.gevent.org/
 .. _Hey: https://github.com/rakyll/hey
-.. _aiohttp: https://github.com/KeepSafe/aiohttp
+.. _aiohttp: https://aiohttp.readthedocs.io/en/stable/
+.. _aiohttp_wsgi: https://aiohttp-wsgi.readthedocs.io/en/stable/index.html
+.. _`example`: https://github.com/benoitc/gunicorn/blob/master/examples/frameworks/flaskapp_aiohttp_wsgi.py

docs/source/news.rst

@@ -2,6 +2,12 @@
 Changelog
 =========
 
+19.8.0 / not released
+=====================
+
+- :pr:`1569`, :pr:`1418` and :issue:`1338`: The ``gaiohttp`` worker is
+  deprecated. See the :ref:`worker-class` documentation for more information.
+
 19.7.1 / 2017/03/21
 ===================
 

docs/source/run.rst

@@ -60,8 +60,10 @@ Commonly Used Arguments
 * ``-k WORKERCLASS, --worker-class=WORKERCLASS`` - The type of worker process
   to run. You'll definitely want to read the production page for the
   implications of this parameter. You can set this to ``$(NAME)``
-  where ``$(NAME)`` is one of ``sync``, ``eventlet``, ``gevent``, or
-  ``tornado``, ``gthread``, ``gaiohttp``. ``sync`` is the default.
+  where ``$(NAME)`` is one of ``sync``, ``eventlet``, ``gevent``,
+  ``tornado``, ``gthread``, ``gaiohttp`` (deprecated).
+  ``sync`` is the default. See the :ref:`worker-class` documentation for more
+  information.
 * ``-n APP_NAME, --name=APP_NAME`` - If setproctitle_ is installed you can
   adjust the name of Gunicorn process as they appear in the process system
   table (which affects tools like ``ps`` and ``top``).

docs/source/settings.rst

@@ -123,13 +123,18 @@ A string referring to one of the following bundled classes:
 * ``gevent``   - Requires gevent >= 0.13
 * ``tornado``  - Requires tornado >= 0.2
 * ``gthread``  - Python 2 requires the futures package to be installed
-* ``gaiohttp`` - Requires Python 3.4 and aiohttp >= 0.21.5
+* ``gaiohttp`` - Deprecated.
 
 Optionally, you can provide your own worker by giving Gunicorn a
 Python path to a subclass of ``gunicorn.workers.base.Worker``.
 This alternative syntax will load the gevent class:
 ``gunicorn.workers.ggevent.GeventWorker``.
 
+.. deprecated:: 19.8
+   The ``gaiohttp`` worker is deprecated. Please use
+   ``aiohttp.worker.GunicornWebWorker`` instead. See
+   :ref:`asyncio-workers` for more information on how to use it.
+
 .. _threads:
 
 threads

examples/frameworks/flaskapp_aiohttp_wsgi.py

@@ -0,0 +1,24 @@
+# Example command to run the example:
+#
+#   $ gunicorn flaskapp_aiohttp_wsgi:aioapp -k aiohttp.worker.GunicornWebWorker
+#
+
+from aiohttp import web
+from aiohttp_wsgi import WSGIHandler
+from flask import Flask
+
+app = Flask(__name__)
+
+
+@app.route('/')
+def hello():
+    return 'Hello, world!'
+
+
+def make_aiohttp_app(app):
+    wsgi_handler = WSGIHandler(app)
+    aioapp = web.Application()
+    aioapp.router.add_route('*', '/{path_info:.*}', wsgi_handler)
+    return aioapp
+
+aioapp = make_aiohttp_app(app)

gunicorn/config.py

@@ -610,12 +610,17 @@ class WorkerClass(Setting):
         * ``gevent``   - Requires gevent >= 0.13
         * ``tornado``  - Requires tornado >= 0.2
         * ``gthread``  - Python 2 requires the futures package to be installed
-        * ``gaiohttp`` - Requires Python 3.4 and aiohttp >= 0.21.5
+        * ``gaiohttp`` - Deprecated.
 
         Optionally, you can provide your own worker by giving Gunicorn a
         Python path to a subclass of ``gunicorn.workers.base.Worker``.
         This alternative syntax will load the gevent class:
         ``gunicorn.workers.ggevent.GeventWorker``.
+
+        .. deprecated:: 19.8
+           The ``gaiohttp`` worker is deprecated. Please use
+           ``aiohttp.worker.GunicornWebWorker`` instead. See
+           :ref:`asyncio-workers` for more information on how to use it.
         """
 
 class WorkerThreads(Setting):

gunicorn/workers/gaiohttp.py

@@ -5,13 +5,23 @@
 
 import sys
 
-if sys.version_info >= (3, 3):
+from gunicorn import util
+
+if sys.version_info >= (3, 4):
     try:
         import aiohttp  # NOQA
     except ImportError:
         raise RuntimeError("You need aiohttp installed to use this worker.")
     else:
-        from gunicorn.workers._gaiohttp import AiohttpWorker
+        try:
+            from aiohttp.worker import GunicornWebWorker as AiohttpWorker
+        except ImportError:
+            from gunicorn.workers._gaiohttp import AiohttpWorker
+
+        util.warn(
+            "The 'gaiohttp' worker is deprecated. See --worker-class "
+            "documentation for more information."
+        )
         __all__ = ['AiohttpWorker']
 else:
-    raise RuntimeError("You need Python >= 3.3 to use the asyncio worker")
+    raise RuntimeError("You need Python >= 3.4 to use the gaiohttp worker")