vscode skill

2026-06-19 16:56:45 -05:00
parent 45d8beda8a
commit 75b0c8d192
9 changed files with 434 additions and 1 deletions
@@ -0,0 +1,98 @@
+# FastAPI Debug Launch with debugpy
+
+This reference provides practical `.vscode/launch.json` patterns for FastAPI applications started with uvicorn.
+
+## Launch FastAPI via Module
+
+Preferred profile:
+
+```json
+{
+  "name": "FastAPI: Uvicorn (debug)",
+  "type": "debugpy",
+  "request": "launch",
+  "module": "uvicorn",
+  "args": [
+    "your_package.main:app",
+    "--host",
+    "127.0.0.1",
+    "--port",
+    "8000",
+    "--reload",
+    "--log-level",
+    "debug"
+  ],
+  "cwd": "${workspaceFolder}",
+  "envFile": "${workspaceFolder}/.env",
+  "console": "integratedTerminal",
+  "justMyCode": true,
+  "jinja": true
+}
+```
+
+Why module mode: it matches `python -m uvicorn ...` behavior and avoids path ambiguity.
+
+## Launch with Factory Pattern
+
+If app is created via factory function:
+
+```json
+{
+  "name": "FastAPI: Uvicorn factory (debug)",
+  "type": "debugpy",
+  "request": "launch",
+  "module": "uvicorn",
+  "args": [
+    "your_package.main:create_app",
+    "--factory",
+    "--host",
+    "127.0.0.1",
+    "--port",
+    "8000",
+    "--reload"
+  ],
+  "cwd": "${workspaceFolder}",
+  "console": "integratedTerminal",
+  "justMyCode": true
+}
+```
+
+## Attach to an Existing FastAPI Process
+
+If the app is launched externally, start with debugpy:
+
+```bash
+python -m debugpy --listen 5678 -m uvicorn your_package.main:app --host 127.0.0.1 --port 8000 --reload
+```
+
+Attach profile:
+
+```json
+{
+  "name": "FastAPI: Attach (5678)",
+  "type": "debugpy",
+  "request": "attach",
+  "connect": {
+    "host": "127.0.0.1",
+    "port": 5678
+  },
+  "justMyCode": true
+}
+```
+
+## Common FastAPI Debug Pitfalls
+
+1. Wrong import target in `your_package.main:app` or factory symbol.
+2. `cwd` does not match source layout.
+3. Auto-reload creating confusion about active process when breakpoints are set in startup code.
+4. Port collisions from old uvicorn processes.
+5. Environment variables not loaded because `envFile` path is wrong.
+
+## Practical Quality Gate
+
+A profile is considered valid when:
+
+1. Server starts from VS Code Run and Debug.
+2. A breakpoint inside an endpoint is hit on request.
+3. A breakpoint in startup/lifespan logic is hit at app boot.
+4. Terminal output appears in integrated terminal with expected log level.