diff --git a/docs/source/design.rst b/docs/source/design.rst index 148fb2ea9..88180a823 100644 --- a/docs/source/design.rst +++ b/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 diff --git a/docs/source/news.rst b/docs/source/news.rst index 16125101f..8ee96a454 100644 --- a/docs/source/news.rst +++ b/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 =================== diff --git a/docs/source/run.rst b/docs/source/run.rst index 48ffdaf12..cfc3ba370 100644 --- a/docs/source/run.rst +++ b/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``). diff --git a/docs/source/settings.rst b/docs/source/settings.rst index 4aab3dbc4..248f061ee 100644 --- a/docs/source/settings.rst +++ b/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 diff --git a/examples/frameworks/flaskapp_aiohttp_wsgi.py b/examples/frameworks/flaskapp_aiohttp_wsgi.py new file mode 100644 index 000000000..05c47b504 --- /dev/null +++ b/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) diff --git a/gunicorn/config.py b/gunicorn/config.py index c127c6578..cab56ea53 100644 --- a/gunicorn/config.py +++ b/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): diff --git a/gunicorn/workers/gaiohttp.py b/gunicorn/workers/gaiohttp.py index 899e9a370..7d0227a8f 100644 --- a/gunicorn/workers/gaiohttp.py +++ b/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")