diff --git a/docs/intro.rst b/docs/intro.rst index 0452ad2..932e968 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -82,8 +82,34 @@ handler functions can be defined as ``async def`` or ``def`` functions, but ``async def`` functions are recommended for performance. The :func:`run() ` method starts the application's web -server on port 5000 by default. This method blocks while it waits for -connections from clients. +server on port 5000 by default, and creates its own asynchronous loop. This +method blocks while it waits for connections from clients. + +For some applications it may be necessary to run the web server alongside other +asynchronous tasks, on an already running loop. In that case, instead of +``app.run()`` the web server can be started by invoking the +:func:`start_server() ` coroutine as shown in +the following example:: + + import asyncio + from microdot import Microdot + + app = Microdot() + + @app.route('/') + async def index(request): + return 'Hello, world!' + + async def main(): + # start the server in a background task + server = asyncio.create_task(app.start_server()) + + # ... do other asynchronous work here ... + + # cleanup before ending the application + await server + + asyncio.run(main()) Running with CPython ^^^^^^^^^^^^^^^^^^^^ @@ -145,8 +171,9 @@ changed by passing the ``port`` argument to the ``run()`` method. Web Server Configuration ^^^^^^^^^^^^^^^^^^^^^^^^ -The :func:`run() ` method supports a few arguments to -configure the web server. +The :func:`run() ` and +:func:`start_server() ` methods support a few +arguments to configure the web server. - ``port``: The port number to listen on. Pass the desired port number in this argument to use a port different than the default of 5000. For example:: diff --git a/pyproject.toml b/pyproject.toml index 5fef9fa..c00ce28 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -14,6 +14,8 @@ classifiers = [ "Operating System :: OS Independent", ] requires-python = ">=3.8" +dependencies = [ +] [project.readme] file = "README.md" @@ -24,6 +26,8 @@ Homepage = "https://github.com/miguelgrinberg/microdot" "Bug Tracker" = "https://github.com/miguelgrinberg/microdot/issues" [project.optional-dependencies] +dev = [ +] docs = [ "sphinx", "pyjwt"