[RFC] fastapi inspect & fastapi attach - wrap Python 3.14’s asyncio cli and pdb for live debugging

[mahimairaja]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched in the documentation/README.
• I already searched in Google "How to do X" and didn't find any information.
• I already read and followed all the tutorial in the docs/README and didn't find an answer.

Commit to Help

• I commit to help with one of those options 👆

Example Code

import os
import sys
import shutil
import subprocess
import typer

app = typer.Typer(help="FastAPI CLI extensions for observability & debugging")

def _ensure(py_mod: str, subcmd: str):
    if shutil.which(sys.executable) is None:
        typer.secho("No Python interpreter found.", fg=typer.colors.RED)
        raise typer.Exit(1)
    # basic sanity check: ensure the module exists
    try:
        __import__(py_mod.replace("-", "_"))
    except Exception:
        # We still proceed; -m invocation will be source of truth.
        pass

@app.command("inspect")
def inspect(
    pid: int = typer.Argument(..., help="Target process ID"),
    tree: bool = typer.Option(False, "--tree", "-t", help="Render coroutine tree"),
):
    """
    wrapper over: python -m asyncio ps|pstree <PID>
    """
    _ensure("asyncio", "ps/pstree")
    sub = "pstree" if tree else "ps"
    cmd = [sys.executable, "-m", "asyncio", sub, str(pid)]
    raise SystemExit(subprocess.call(cmd))

@app.command("attach")
def attach(
    pid: int = typer.Argument(..., help="Target process ID"),
):
    """
    Wrapper over: python -m pdb -p <PID>
    """
    _ensure("pdb", "attach")
    # On POSIX, you typically need to be the same user or root.
    cmd = [sys.executable, "-m", "pdb", "-p", str(pid)]
    # Forward TTY so interactive session works.
    raise SystemExit(subprocess.call(cmd))

if __name__ == "__main__":
    app()

Description

Overview

Python 3.14 added first-class process-introspection for asyncio and a remote-attach mode for pdb. Surfacing these via FastAPI’s CLI would give developers “works everywhere” observability/debugging for live FastAPI services, without extra agents or pre-instrumentation.

Read more on: PEP 768 and Asynchronous CLI

Proposed UX (small & incremental):

fastapi inspect --pid <PID> [--tree]
A pretty wrapper over python -m asyncio ps (flat task table) and python -m asyncio pstree (hierarchical coroutine tree). These 3.14 tools can introspect async tasks across threads.

fastapi attach --pid <PID>
A thin wrapper over python -m pdb -p for interactive debugging of a running process. This is a new 3.14 feature built atop the safe external debugger interface.

Notes / safety:

• Attaching/debugging requires appropriate privileges and a controlling TTY. The CLI can show a safety banner (e.g., “You are entering an interactive debugger on PID X”).
• Optional future enhancement: annotate tasks with route/middleware names if the target app exposes a small, opt-in hook.

Operating System

Linux, Windows, macOS

Operating System Details

POSIX: typically same user or root to attach to another PID.

Windows: run in an elevated console when required.

Python Version

Python 3.14+

Additional Context

If maintainers agree, I’m happy to help with a small PR adding these two subcommands to fastapi-cli. Would love to discuss. Thanks!