✨ Async support optionally using anyio

.github/workflows/test.yml

@@ -22,8 +22,6 @@ jobs:
         os: [ ubuntu-latest, windows-latest, macos-latest ]
         python-version: [ "3.13" ]
         include:
-          - os: ubuntu-22.04
-            python-version: "3.7"
           - os: macos-latest
             python-version: "3.8"
           - os: windows-latest

README.md

@@ -358,6 +358,8 @@ By default it also comes with extra standard dependencies:
 * <a href="https://github.com/sarugaku/shellingham" class="external-link" target="_blank"><code>shellingham</code></a>: to automatically detect the current shell when installing completion.
     * With `shellingham` you can just use `--install-completion`.
     * Without `shellingham`, you have to pass the name of the shell to install completion for, e.g. `--install-completion bash`.
+* <a href="https://github.com/agronholm/anyio" class="external-link" target="_blank"><code>anyio</code></a>: and Typer will automatically detect the appropriate engine to run asynchronous code.
+    * With <a href="https://github.com/python-trio/trio" class="external-link" target="_blank"><code>Trio</code></a> installed alongside Typer, Typer will use Trio to run asynchronous code by default.
 
 ### `typer-slim`
 

docs/features.md

@@ -16,6 +16,10 @@ If you need a 2 minute refresher of how to use Python types (even if you don't u
 
 You will also see a 20 seconds refresher on the section [Tutorial - User Guide: First Steps](tutorial/first-steps.md){.internal-link target=_blank}.
 
+## Async support
+
+Supports **asyncio** out of the box. [AnyIO](https://github.com/agronholm/anyio) is available as extra dependency for automatic support of [Trio](https://github.com/python-trio/trio).
+
 ## Editor support
 
 **Typer** was designed to be easy and intuitive to use, to ensure the best development experience. With autocompletion everywhere.

docs/index.md

@@ -364,6 +364,8 @@ By default it also comes with extra standard dependencies:
 * <a href="https://github.com/sarugaku/shellingham" class="external-link" target="_blank"><code>shellingham</code></a>: to automatically detect the current shell when installing completion.
     * With `shellingham` you can just use `--install-completion`.
     * Without `shellingham`, you have to pass the name of the shell to install completion for, e.g. `--install-completion bash`.
+* <a href="https://github.com/agronholm/anyio" class="external-link" target="_blank"><code>anyio</code></a>: and Typer will automatically detect the appropriate engine to run asynchronous code.
+    * With <a href="https://github.com/python-trio/trio" class="external-link" target="_blank"><code>Trio</code></a> installed alongside Typer, Typer will use Trio to run asynchronous code by default.
 
 ### `typer-slim`
 

docs/tutorial/async.md

@@ -0,0 +1,88 @@
+# Async support
+
+## Engines
+
+Typer supports `asyncio` out of the box. <a href="https://github.com/python-trio/trio" class="external-link" target="_blank"><code>Trio</code></a> is supported through
+<a href="https://github.com/agronholm/anyio" class="external-link" target="_blank"><code>anyio</code></a>, which can be installed as optional dependency:
+
+<div class="termy">
+
+```console
+$ pip install typer[anyio]
+---> 100%
+Successfully installed typer anyio
+```
+
+</div>
+
+### Default engine selection
+
+*none* | anyio | trio | anyio + trio
+--- | --- | --- | ---
+asyncio | asyncio via anyio | asyncio* | trio via anyio
+
+<small>* If you don't want to install `anyio` when using `trio`, provide your own async_runner function</small>
+
+## Using with run()
+
+Async functions can be run just like normal functions:
+
+```Python
+{!../docs_src/asynchronous/tutorial001.py!}
+```
+
+Or using `anyio`:
+
+```Python
+{!../docs_src/asynchronous/tutorial002.py!}
+```
+
+<small>Important to note, `typer.run()` doesn't provide means to customize the async run behavior.</small>
+
+## Using with commands
+
+Async functions can be registered as commands just like synchronous functions:
+
+```Python
+{!../docs_src/asynchronous/tutorial003.py!}
+```
+
+Or using `anyio`:
+
+```Python
+{!../docs_src/asynchronous/tutorial004.py!}
+```
+
+Or using `trio` via `anyio`:
+
+```Python
+{!../docs_src/asynchronous/tutorial005.py!}
+```
+
+## Using with callback
+
+The callback function supports asynchronous functions just like commands including the `async_runner` parameter:
+
+```Python
+{!../docs_src/asynchronous/tutorial006.py!}
+```
+
+Because the asynchronous functions are wrapped in a synchronous context before being executed, it is possible to mix async engines between the callback and commands.
+
+## Customizing async engine
+
+Customizing the used async engine is as simple as providing an additional parameter to the Typer instance or the decorators.
+
+The `async_runner` provided to the decorator always overwrites the typer instances `async_runner`.
+
+Customize a single command:
+
+```Python
+{!../docs_src/asynchronous/tutorial007.py!}
+```
+
+Customize the default engine for the Typer instance:
+
+```Python
+{!../docs_src/asynchronous/tutorial008.py!}
+```

docs_src/asynchronous/tutorial001.py

@@ -0,0 +1,15 @@
+import asyncio
+
+import typer
+
+app = typer.Typer()
+
+
+@app.command()
+async def main():
+    await asyncio.sleep(1)
+    typer.echo("Hello World")
+
+
+if __name__ == "__main__":
+    app()

docs_src/asynchronous/tutorial002.py

@@ -0,0 +1,14 @@
+import anyio
+import typer
+
+app = typer.Typer()
+
+
+@app.command()
+async def main():
+    await anyio.sleep(1)
+    typer.echo("Hello World")
+
+
+if __name__ == "__main__":
+    app()

docs_src/asynchronous/tutorial003.py

@@ -0,0 +1,15 @@
+import asyncio
+
+import typer
+
+app = typer.Typer(async_runner=asyncio.run)
+
+
+@app.command()
+async def wait(seconds: int):
+    await asyncio.sleep(seconds)
+    typer.echo(f"Waited for {seconds} seconds")
+
+
+if __name__ == "__main__":
+    app()

docs_src/asynchronous/tutorial004.py

@@ -0,0 +1,14 @@
+import anyio
+import typer
+
+app = typer.Typer()
+
+
+@app.command()
+async def wait(seconds: int):
+    await anyio.sleep(seconds)
+    typer.echo(f"Waited for {seconds} seconds")
+
+
+if __name__ == "__main__":
+    app()

docs_src/asynchronous/tutorial005.py

@@ -0,0 +1,14 @@
+import trio
+import typer
+
+app = typer.Typer()
+
+
+@app.command()
+async def wait(seconds: int):
+    await trio.sleep(seconds)
+    typer.echo(f"Waited for {seconds} seconds")
+
+
+if __name__ == "__main__":
+    app()

docs_src/asynchronous/tutorial006.py

@@ -0,0 +1,24 @@
+import asyncio
+
+import trio
+import typer
+
+app = typer.Typer()
+
+
+@app.command()
+async def wait_trio(seconds: int):
+    await trio.sleep(seconds)
+    typer.echo(f"Waited for {seconds} seconds using trio (default)")
+
+
+@app.callback(async_runner=lambda c: asyncio.run(c))
+async def wait_asyncio(seconds: int):
+    await asyncio.sleep(seconds)
+    typer.echo(
+        f"Waited for {seconds} seconds before running command using asyncio (customized)"
+    )
+
+
+if __name__ == "__main__":
+    app()

docs_src/asynchronous/tutorial007.py

@@ -0,0 +1,22 @@
+import asyncio
+
+import trio
+import typer
+
+app = typer.Typer()
+
+
+@app.command()
+async def wait_trio(seconds: int):
+    await trio.sleep(seconds)
+    typer.echo(f"Waited for {seconds} seconds using trio (default)")
+
+
+@app.command(async_runner=asyncio.run)
+async def wait_asyncio(seconds: int):
+    await asyncio.sleep(seconds)
+    typer.echo(f"Waited for {seconds} seconds using asyncio (custom runner)")
+
+
+if __name__ == "__main__":
+    app()

docs_src/asynchronous/tutorial008.py

@@ -0,0 +1,22 @@
+import asyncio
+
+import anyio
+import typer
+
+app = typer.Typer(async_runner=lambda c: anyio.run(lambda: c, backend="asyncio"))
+
+
+@app.command()
+async def wait_anyio(seconds: int):
+    await anyio.sleep(seconds)
+    typer.echo(f"Waited for {seconds} seconds using asyncio via anyio")
+
+
+@app.command()
+async def wait_asyncio(seconds: int):
+    await asyncio.sleep(seconds)
+    typer.echo(f"Waited for {seconds} seconds using asyncio")
+
+
+if __name__ == "__main__":
+    app()

mkdocs.yml

@@ -133,6 +133,7 @@ nav:
       - tutorial/testing.md
       - tutorial/using-click.md
       - tutorial/package.md
+      - tutorial/async.md
       - tutorial/exceptions.md
       - tutorial/one-file-per-command.md
       - tutorial/typer-command.md

requirements-tests.txt

@@ -5,8 +5,12 @@ pytest-cov >=2.10.0,<7.0.0
 coverage[toml] >=6.2,<8.0
 pytest-xdist >=1.32.0,<4.0.0
 pytest-sugar >=0.9.4,<1.2.0
+pytest-mock >=3.11.1
 mypy ==1.4.1
 ruff ==0.12.11
+anyio >=4.0.0
+filelock >=3.4.0,<4.0.0
+trio >=0.22
 # Needed explicitly by typer-slim
 rich >=10.11.0
 shellingham >=1.3.0

tests/test_completion/conftest.py

@@ -0,0 +1,26 @@
+import pytest
+from filelock import FileLock
+
+
+@pytest.fixture
+def bashrc_lock():
+    with FileLock(".bachrc.lock"):
+        yield
+
+
+@pytest.fixture
+def zshrc_lock():
+    with FileLock(".zsh.lock"):
+        yield
+
+
+@pytest.fixture
+def fish_config_lock():
+    with FileLock(".fish.lock"):
+        yield
+
+
+@pytest.fixture
+def powershell_profile_lock():
+    with FileLock(".powershell.lock"):
+        yield

tests/test_completion/for_testing/commands_help_tutorial001_async.py

@@ -0,0 +1,58 @@
+import typer
+
+app = typer.Typer(help="Awesome CLI user manager.")
+
+
+@app.command()
+async def create(username: str):
+    """
+    Create a new user with USERNAME.
+    """
+    typer.echo(f"Creating user: {username}")
+
+
+@app.command()
+async def delete(
+    username: str,
+    # force: bool = typer.Option(False, "--force")
+    force: bool = typer.Option(
+        False,
+        prompt="Are you sure you want to delete the user?",
+        help="Force deletion without confirmation.",
+    ),
+):
+    """
+    Delete a user with USERNAME.
+
+    If --force is not used, will ask for confirmation.
+    """
+    typer.echo(f"Deleting user: {username}" if force else "Operation cancelled")
+
+
+@app.command()
+async def delete_all(
+    force: bool = typer.Option(
+        False,
+        prompt="Are you sure you want to delete ALL users?",
+        help="Force deletion without confirmation.",
+    ),
+):
+    """
+    Delete ALL users in the database.
+
+    If --force is not used, will ask for confirmation.
+    """
+
+    typer.echo("Deleting all users" if force else "Operation cancelled")
+
+
+@app.command()
+async def init():
+    """
+    Initialize the users database.
+    """
+    typer.echo("Initializing user database")
+
+
+if __name__ == "__main__":
+    app()

tests/test_completion/for_testing/commands_index_tutorial002_async.py

@@ -0,0 +1,17 @@
+import typer
+
+app = typer.Typer()
+
+
+@app.command()
+def create():
+    typer.echo("Creating user: Hiro Hamada")
+
+
+@app.command()
+def delete():
+    typer.echo("Deleting user: Hiro Hamada")
+
+
+if __name__ == "__main__":
+    app()