From 5260d1f71ba04d7ef99a7d8de4969cb42e70b65d Mon Sep 17 00:00:00 2001 From: Marcelo Trylesinski Date: Sat, 18 Jun 2022 18:49:06 +0200 Subject: [PATCH 1/5] Document how to run uvicorn programatically --- docs/index.md | 44 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 472c92ca1..b1ee3f2d8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -196,9 +196,25 @@ For more information, see the [settings documentation](settings.md). ### Running programmatically -To run uvicorn directly from your application... +There are many ways to run uvicorn directly from your application. -**example.py**: +#### `uvicorn.run` function + +The easiest way is to run via `uvicorn.run` function: + +```python +import uvicorn + +async def app(scope, receive, send): + ... + +if __name__ == "__main__": + uvicorn.run("main:app", host="127.0.0.1", port=5000, log_level="info") +``` + +#### Explicitly setup `Config` and `Server` instances + +You can create the `uvicorn.Config` and `uvicorn.Server` instances manually, and then use `uvicorn.Server.run()`: ```python import uvicorn @@ -207,7 +223,29 @@ async def app(scope, receive, send): ... if __name__ == "__main__": - uvicorn.run("example:app", host="127.0.0.1", port=5000, log_level="info") + config = uvicorn.Config("main:app", host="127.0.0.1", post=5000, log_level="info") + server = uvicorn.Server(config) + server.run() +``` + +#### Run inside the event loop + +There are cases that `async` logic needs to be performed, and it's interesting to run `uvicorn` inside the event loop: + +```python +import asyncio +import uvicorn + +async def app(scope, receive, send): + ... + +async def main(): + config = uvicorn.Config("main:app", host="127.0.0.1", post=5000, log_level="info") + server = uvicorn.Server(config) + await server.serve() + +if __name__ == "__main__": + asyncio.run(main()) ``` ### Running with Gunicorn From fdce7cc6fb2907b193ef879847a75f6b26b4d5c7 Mon Sep 17 00:00:00 2001 From: Marcelo Trylesinski Date: Sun, 19 Jun 2022 18:17:03 +0200 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Florimond Manca --- docs/index.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/index.md b/docs/index.md index b1ee3f2d8..a2a9faeb5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -196,11 +196,11 @@ For more information, see the [settings documentation](settings.md). ### Running programmatically -There are many ways to run uvicorn directly from your application. +There are several ways to run uvicorn directly from your application. -#### `uvicorn.run` function +#### `uvicorn.run` -The easiest way is to run via `uvicorn.run` function: +If you're looking for a programmatic equivalent of the `uvicorn` command line interface, use `uvicorn.run()`: ```python import uvicorn @@ -214,7 +214,7 @@ if __name__ == "__main__": #### Explicitly setup `Config` and `Server` instances -You can create the `uvicorn.Config` and `uvicorn.Server` instances manually, and then use `uvicorn.Server.run()`: +For more control over configuration and server lifecycle, use `uvicorn.Config` and `uvicorn.Server`: ```python import uvicorn @@ -228,9 +228,7 @@ if __name__ == "__main__": server.run() ``` -#### Run inside the event loop - -There are cases that `async` logic needs to be performed, and it's interesting to run `uvicorn` inside the event loop: +If you'd like to run Uvicorn from an already running async environment, use `uvicorn.Server.serve()` instead: ```python import asyncio From 85b24df7636931a0fa5965a891f60332eac1f56c Mon Sep 17 00:00:00 2001 From: Marcelo Trylesinski Date: Sun, 19 Jun 2022 18:17:16 +0200 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Florimond Manca --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index a2a9faeb5..28c6d3377 100644 --- a/docs/index.md +++ b/docs/index.md @@ -212,7 +212,7 @@ if __name__ == "__main__": uvicorn.run("main:app", host="127.0.0.1", port=5000, log_level="info") ``` -#### Explicitly setup `Config` and `Server` instances +#### `Config` and `Server` instances For more control over configuration and server lifecycle, use `uvicorn.Config` and `uvicorn.Server`: From 936ce90661d0fb5a54574d00120115019f2153a8 Mon Sep 17 00:00:00 2001 From: Marcelo Trylesinski Date: Sun, 19 Jun 2022 18:22:26 +0200 Subject: [PATCH 4/5] Shrink configuration command --- docs/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 28c6d3377..c3d1ca5b0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -209,7 +209,7 @@ async def app(scope, receive, send): ... if __name__ == "__main__": - uvicorn.run("main:app", host="127.0.0.1", port=5000, log_level="info") + uvicorn.run("main:app", port=5000, log_level="info") ``` #### `Config` and `Server` instances @@ -223,7 +223,7 @@ async def app(scope, receive, send): ... if __name__ == "__main__": - config = uvicorn.Config("main:app", host="127.0.0.1", post=5000, log_level="info") + config = uvicorn.Config("main:app", port=5000, log_level="info") server = uvicorn.Server(config) server.run() ``` @@ -238,7 +238,7 @@ async def app(scope, receive, send): ... async def main(): - config = uvicorn.Config("main:app", host="127.0.0.1", post=5000, log_level="info") + config = uvicorn.Config("main:app", port=5000, log_level="info") server = uvicorn.Server(config) await server.serve() From e7930c5adeeab3331aaef91c40a41d6fd381e4cc Mon Sep 17 00:00:00 2001 From: Marcelo Trylesinski Date: Mon, 20 Jun 2022 22:02:14 +0200 Subject: [PATCH 5/5] Update docs/index.md --- docs/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.md b/docs/index.md index c3d1ca5b0..3d6a67fa6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -203,6 +203,7 @@ There are several ways to run uvicorn directly from your application. If you're looking for a programmatic equivalent of the `uvicorn` command line interface, use `uvicorn.run()`: ```python +# main.py import uvicorn async def app(scope, receive, send):