From e09b405832c196f632cbb17fbfda2e1890010b9b Mon Sep 17 00:00:00 2001 From: Sam Bull Date: Tue, 9 Nov 2021 22:41:41 +0000 Subject: [PATCH 1/7] Add additional information on running complex apps. --- docs/web_advanced.rst | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/web_advanced.rst b/docs/web_advanced.rst index 0476b5f1fa..e0a53b447d 100644 --- a/docs/web_advanced.rst +++ b/docs/web_advanced.rst @@ -897,6 +897,48 @@ The task ``listen_to_redis`` will run forever. To shut it down correctly :attr:`Application.on_cleanup` signal handler may be used to send a cancellation to it. +Complex Applications +++++++++++++++++++++ + +Sometimes aiohttp is not the sole part of an application and additional +tasks/processes may need to be run alongside the aiohttp :class:`Application`. + +Generally, the best way to achieve this is to use :func:`aiohttp.web.run_app` +as the entry point for the program. Other tasks can then be run via +:attr:`Application.startup` and :attr:`Application.on_cleanup`. By having the +:class:`Application` control the lifecycle of the entire program, the code +will be more robust and ensure that the tasks are started and stopped along +with the application. + +For example, running a long-lived task alongside the :class:`Application` +can be done with a cleanup_ctx function like:: + + + async def run_other_task(_app): + task = asyncio.create_task(other_long_task()) + + yield + + task.cancel() + with suppress(asyncio.CancelledError): + await task # Ensure any exceptions etc. are raised. + + +Or a separate process can be run with something like:: + + + async def run_process(_app): + proc = await asyncio.create_subprocess_exec(path) + + yield + + if proc.returncode is None: + proc.terminate() + await proc.wait() + + app.cleanup_ctx.append(run_process) + + Handling error pages -------------------- From baca6a4ae659bdbe44eb6be8d9949d0d9438dc06 Mon Sep 17 00:00:00 2001 From: Sam Bull Date: Tue, 9 Nov 2021 22:52:05 +0000 Subject: [PATCH 2/7] Tweak run_app() documentation. --- docs/web_reference.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/web_reference.rst b/docs/web_reference.rst index 5ab08f946f..bc60bcabd2 100644 --- a/docs/web_reference.rst +++ b/docs/web_reference.rst @@ -2784,13 +2784,15 @@ Utilities reuse_address=None, \ reuse_port=None) - A utility function for running an application, serving it until + A high-level function for running an application, serving it until keyboard interrupt and performing a :ref:`aiohttp-web-graceful-shutdown`. - Suitable as handy tool for scaffolding aiohttp based projects. - Perhaps production config will use more sophisticated runner but it - good enough at least at very beginning stage. + This is a high-level function very similar to :func:`asyncio.run` and + should be used as the main entry point for an application. The + :class:`Application` object essentially becomes our `main()` function. + If additional tasks need to be run in parallel, see + :ref:`aiohttp-web-complex-applications`. The server will listen on any host or Unix domain socket path you supply. If no hosts or paths are supplied, or only a port is supplied, a TCP server From 0cdb4d39b9bb65562266b510257d25708511e19c Mon Sep 17 00:00:00 2001 From: Sam Bull Date: Tue, 9 Nov 2021 22:53:27 +0000 Subject: [PATCH 3/7] Add anchor. --- docs/web_advanced.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/web_advanced.rst b/docs/web_advanced.rst index e0a53b447d..b336d07f0f 100644 --- a/docs/web_advanced.rst +++ b/docs/web_advanced.rst @@ -897,6 +897,8 @@ The task ``listen_to_redis`` will run forever. To shut it down correctly :attr:`Application.on_cleanup` signal handler may be used to send a cancellation to it. +.. _aiohttp-web-complex-applications: + Complex Applications ++++++++++++++++++++ From 0b8f76b473de5191854ef87a51bd090346dcd279 Mon Sep 17 00:00:00 2001 From: Sam Bull Date: Tue, 9 Nov 2021 22:57:12 +0000 Subject: [PATCH 4/7] Missing line. --- docs/web_advanced.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/web_advanced.rst b/docs/web_advanced.rst index b336d07f0f..a8dc35dd85 100644 --- a/docs/web_advanced.rst +++ b/docs/web_advanced.rst @@ -925,6 +925,8 @@ can be done with a cleanup_ctx function like:: with suppress(asyncio.CancelledError): await task # Ensure any exceptions etc. are raised. + app.cleanup_ctx.append(run_other_task) + Or a separate process can be run with something like:: From f3032908f8e26bf79a6140decc1093a3a3d1946a Mon Sep 17 00:00:00 2001 From: Sam Bull Date: Tue, 9 Nov 2021 23:00:08 +0000 Subject: [PATCH 5/7] Create 6278.doc --- CHANGES/6278.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 CHANGES/6278.doc diff --git a/CHANGES/6278.doc b/CHANGES/6278.doc new file mode 100644 index 0000000000..2d18217379 --- /dev/null +++ b/CHANGES/6278.doc @@ -0,0 +1 @@ +Added information on running complex applications with additional tasks/processes -- :user:`Dreamsorcerer`. From 99e00bd978f3570470526706f234f86fbad79fa8 Mon Sep 17 00:00:00 2001 From: Sam Bull Date: Tue, 9 Nov 2021 23:05:03 +0000 Subject: [PATCH 6/7] Update web_advanced.rst --- docs/web_advanced.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/web_advanced.rst b/docs/web_advanced.rst index a8dc35dd85..7d5465c3ec 100644 --- a/docs/web_advanced.rst +++ b/docs/web_advanced.rst @@ -913,7 +913,7 @@ will be more robust and ensure that the tasks are started and stopped along with the application. For example, running a long-lived task alongside the :class:`Application` -can be done with a cleanup_ctx function like:: +can be done with a :ref:`aiohttp-web-cleanup-ctx` function like:: async def run_other_task(_app): From 8c9c6a96470f382b5ef1de036bb2e1f57ca34c01 Mon Sep 17 00:00:00 2001 From: Sam Bull Date: Tue, 9 Nov 2021 23:08:38 +0000 Subject: [PATCH 7/7] Update web_advanced.rst --- docs/web_advanced.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/web_advanced.rst b/docs/web_advanced.rst index 7d5465c3ec..480becf97c 100644 --- a/docs/web_advanced.rst +++ b/docs/web_advanced.rst @@ -900,7 +900,7 @@ may be used to send a cancellation to it. .. _aiohttp-web-complex-applications: Complex Applications -++++++++++++++++++++ +^^^^^^^^^^^^^^^^^^^^ Sometimes aiohttp is not the sole part of an application and additional tasks/processes may need to be run alongside the aiohttp :class:`Application`.