✨ Async support optionally using anyio

README.md

@@ -360,6 +360,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

@@ -366,6 +366,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,70 @@
+# 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:
+
+{* docs_src/asynchronous/tutorial001.py hl[1,8:9,14] *}
+
+Or using `anyio`:
+
+{* docs_src/asynchronous/tutorial002.py hl[1,8] *}
+
+## Using with commands
+
+Async functions can be registered as commands explicitely just like synchronous functions:
+
+{* docs_src/asynchronous/tutorial003.py hl[1,8:9,15] *}
+
+Or using `anyio`:
+
+{* docs_src/asynchronous/tutorial004.py hl[1,9] *}
+
+Or using `trio` via `anyio`:
+
+{* docs_src/asynchronous/tutorial005.py hl[1,9] *}
+
+## Customizing async engine
+
+You can customize the async engine by providing an additional parameter `async_runner` to the Typer instance or to the command decorator.
+
+When both are provided, the one from the decorator will take precedence over the one from the Typer instance.
+
+Customize a single command:
+
+{* docs_src/asynchronous/tutorial007.py hl[15] *}
+
+Customize the default engine for the Typer instance:
+
+{* docs_src/asynchronous/tutorial008.py hl[6] *}
+
+## Using with callback
+
+The callback function supports asynchronous functions with the `async_runner` parameter as well:
+
+{* docs_src/asynchronous/tutorial006.py hl[15] *}
+
+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.

docs_src/asynchronous/tutorial001.py

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

docs_src/asynchronous/tutorial002.py

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

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,<8.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.14.1
 ruff ==0.14.5
+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()

tests/test_completion/test_commands_index_tutorial002_async.py

@@ -0,0 +1,21 @@
+from typer.testing import CliRunner
+
+from tests.test_completion.for_testing import (
+    commands_index_tutorial002_async as async_mod,
+)
+
+app = async_mod.app
+
+runner = CliRunner()
+
+
+def test_create():
+    result = runner.invoke(app, ["create"])
+    assert result.exit_code == 0
+    assert "Creating user: Hiro Hamada" in result.output
+
+
+def test_delete():
+    result = runner.invoke(app, ["delete"])
+    assert result.exit_code == 0
+    assert "Deleting user: Hiro Hamada" in result.output