fastapi-therapist 0.1.0__tar.gz

fastapi_therapist-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

fastapi_therapist-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: fastapi-therapist
+Version: 0.1.0
+Summary: Diagnose FastAPI codebases for best practices
+Project-URL: Homepage, https://github.com/sahil-code-19/FastAPI-doctor
+Project-URL: Repository, https://github.com/sahil-code-19/FastAPI-doctor
+Author-email: Sahil Koshti <koshtisahil02@gmail.com>
+License: MIT
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# fastapi-therapist
+
+Diagnose FastAPI codebases for security, performance, correctness, and architecture issues. Outputs a 0–100 health score.
+
+## Installation
+
+```bash
+pip install fastapi-therapist
+```
+
+## Usage
+
+```bash
+# Scan current directory with verbose output
+fastapi-therapist . --verbose
+
+# Scan a specific project
+fastapi-therapist /path/to/fastapi/project --verbose
+
+# Output only the score (useful for CI)
+fastapi-therapist . --score
+```
+
+## Rules
+
+### Async/Sync Correctness
+
+| Rule | Severity | Detects |
+|---|---|---|
+| FASTT001 | ERROR | Sync blocking IO (`requests.get`, `time.sleep`) in async endpoint |
+| FASTT002 | ERROR | Sync SQLAlchemy calls in async endpoint |
+| FASTT003 | WARN/ERROR | `async def` endpoint with no await |
+| FASTT004 | ERROR | `asyncio.run()` inside async context — nested event loop |
+| FASTT005 | ERROR | `open()` blocking file I/O in async endpoint |
+| FASTT006 | WARNING | `subprocess.run()` / `os.system()` in async endpoint |
+
+### Correctness
+
+| Rule | Severity | Detects |
+|---|---|---|
+| FASTT011 | WARNING | POST/PUT/PATCH/DELETE missing explicit `status_code` |
+
+## Score
+
+The health score formula:
+
+```
+100 - (unique error rules × 1.5) - (unique warning rules × 0.75)
+```
+
+- **75–100** Great
+- **50–74** Needs work
+- **0–49** Critical

fastapi_therapist-0.1.0/README.md

@@ -0,0 +1,53 @@
+# fastapi-therapist
+
+Diagnose FastAPI codebases for security, performance, correctness, and architecture issues. Outputs a 0–100 health score.
+
+## Installation
+
+```bash
+pip install fastapi-therapist
+```
+
+## Usage
+
+```bash
+# Scan current directory with verbose output
+fastapi-therapist . --verbose
+
+# Scan a specific project
+fastapi-therapist /path/to/fastapi/project --verbose
+
+# Output only the score (useful for CI)
+fastapi-therapist . --score
+```
+
+## Rules
+
+### Async/Sync Correctness
+
+| Rule | Severity | Detects |
+|---|---|---|
+| FASTT001 | ERROR | Sync blocking IO (`requests.get`, `time.sleep`) in async endpoint |
+| FASTT002 | ERROR | Sync SQLAlchemy calls in async endpoint |
+| FASTT003 | WARN/ERROR | `async def` endpoint with no await |
+| FASTT004 | ERROR | `asyncio.run()` inside async context — nested event loop |
+| FASTT005 | ERROR | `open()` blocking file I/O in async endpoint |
+| FASTT006 | WARNING | `subprocess.run()` / `os.system()` in async endpoint |
+
+### Correctness
+
+| Rule | Severity | Detects |
+|---|---|---|
+| FASTT011 | WARNING | POST/PUT/PATCH/DELETE missing explicit `status_code` |
+
+## Score
+
+The health score formula:
+
+```
+100 - (unique error rules × 1.5) - (unique warning rules × 0.75)
+```
+
+- **75–100** Great
+- **50–74** Needs work
+- **0–49** Critical

fastapi_therapist-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "fastapi-therapist"
+version = "0.1.0"
+description = "Diagnose FastAPI codebases for best practices"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = []
+authors = [
+    { name = "Sahil Koshti", email = "koshtisahil02@gmail.com" },
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: FastAPI",
+]
+
+[project.urls]
+Homepage = "https://github.com/sahil-code-19/FastAPI-doctor"
+Repository = "https://github.com/sahil-code-19/FastAPI-doctor"
+
+[project.scripts]
+fastapi-therapist = "fastapi_doctor.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fastapi_doctor"]

fastapi_therapist-0.1.0/src/fastapi_doctor/cli.py

@@ -0,0 +1,53 @@
+import argparse
+import sys
+from pathlib import Path
+from .scanner import scan_directory
+from .scoring import calculate_score
+from .reporter import print_header, print_diagnostics, print_score, print_summary
+
+VERSION = "0.1.0"
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="fastapi-therapist",
+        description="Diagnose FastAPI codebases for best practices",
+    )
+    parser.add_argument("directory", nargs="?", default=".", help="Directory to scan")
+    parser.add_argument(
+        "-v", "--version", action="version", version=f"%(prog)s {VERSION}"
+    )
+    parser.add_argument(
+        "--verbose", action="store_true", help="Show all file locations"
+    )
+    parser.add_argument("--score", action="store_true", help="Output only the score")
+
+    args = parser.parse_args()
+
+    directory = Path(args.directory).resolve()
+    if not directory.is_dir():
+        print(f"Error: {directory} is not a directory", file=sys.stderr)
+        sys.exit(1)
+
+    if not args.score:
+        print_header(VERSION)
+
+    result = scan_directory(directory)
+    score_result = calculate_score(result.diagnostics)
+
+    if args.score:
+        print(score_result.score)
+        return
+
+    print_diagnostics(result.diagnostics, verbose=args.verbose)
+    print()
+    print_score(score_result)
+    print_summary(result.diagnostics, result.files_scanned, result.elapsed_ms)
+
+    # Exit with error if there are errors
+    if any(d.severity.value == "error" for d in result.diagnostics):
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

fastapi_therapist-0.1.0/src/fastapi_doctor/models.py

@@ -0,0 +1,39 @@
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Severity(Enum):
+    ERROR = "error"
+    WARNING = "warning"
+
+
+@dataclass
+class Diagnostic:
+    file_path: str
+    rule: str
+    severity: Severity
+    message: str
+    line: int
+    column: int
+    help: str = ""
+
+
+@dataclass
+class RuleDefinition:
+    id: str
+    severity: Severity
+    description: str
+    recommendation: str
+
+
+@dataclass
+class ScanResult:
+    diagnostics: list[Diagnostic]
+    files_scanned: int
+    elapsed_ms: float
+
+
+@dataclass
+class ScoreResult:
+    score: int
+    label: str

fastapi_therapist-0.1.0/src/fastapi_doctor/reporter.py

@@ -0,0 +1,64 @@
+from .models import Diagnostic, ScoreResult, Severity
+
+# ANSI colors
+RED = "\033[91m"
+YELLOW = "\033[93m"
+GREEN = "\033[92m"
+GRAY = "\033[90m"
+BOLD = "\033[1m"
+RESET = "\033[0m"
+
+
+def print_header(version: str):
+    print(f"{BOLD}FastAPI Therapist{RESET} v{version}")
+    print()
+
+
+def print_diagnostics(diagnostics: list[Diagnostic], verbose: bool = False):
+    if not diagnostics:
+        print(f"{GREEN}No issues found!{RESET}")
+        return
+
+    # Group by rule + severity so mixed-severity rules get separate headers
+    by_rule_severity: dict[tuple[str, str], list[Diagnostic]] = {}
+    for diag in diagnostics:
+        key = (diag.rule, diag.severity.value)
+        by_rule_severity.setdefault(key, []).append(diag)
+
+    for (rule, severity_value), rule_diags in by_rule_severity.items():
+        is_error = severity_value == Severity.ERROR.value
+        severity_icon = "X" if is_error else "!"
+        color = RED if is_error else YELLOW
+
+        print(f"  {color}{severity_icon} {rule}{RESET} ({len(rule_diags)} issues)")
+
+        for diag in rule_diags:
+            print(
+                f"    {color}→{RESET} {GRAY}{diag.file_path}:{diag.line}{RESET}  {diag.message}"
+            )
+
+        if rule_diags[0].help:
+            print(f"    {GRAY}-> {rule_diags[0].help}{RESET}")
+
+        print()
+
+
+def print_score(score_result: ScoreResult):
+    color = (
+        GREEN
+        if score_result.score >= 75
+        else YELLOW
+        if score_result.score >= 50
+        else RED
+    )
+    print(
+        f"{BOLD}Score:{RESET} {color}{score_result.score}/100{RESET} ({score_result.label})"
+    )
+
+
+def print_summary(diagnostics: list[Diagnostic], files_scanned: int, elapsed_ms: float):
+    errors = sum(1 for d in diagnostics if d.severity == Severity.ERROR)
+    warnings = sum(1 for d in diagnostics if d.severity == Severity.WARNING)
+    print(f"{GRAY}Scanned {files_scanned} files in {elapsed_ms:.0f}ms{RESET}")
+    if diagnostics:
+        print(f"{GRAY}{errors} errors, {warnings} warnings{RESET}")

fastapi_therapist-0.1.0/src/fastapi_doctor/rules/__init__.py

@@ -0,0 +1,9 @@
+# Import all rule modules here to trigger @register_rule decorator
+from .async_sync import DbSessionInAsyncRule, SyncBlockingIORule
+from .correctness import MissingStatusCodeRule
+
+__all__ = [
+    "DbSessionInAsyncRule",
+    "MissingStatusCodeRule",
+    "SyncBlockingIORule",
+]

fastapi_therapist-0.1.0/src/fastapi_doctor/rules/async_sync/__init__.py

@@ -0,0 +1,15 @@
+from .fastt001_sync_blocking_io import SyncBlockingIORule
+from .fastt002_db_session_in_async import DbSessionInAsyncRule
+from .fastt003_no_await_in_async import NoAwaitInAsyncRule
+from .fastt004_nested_event_loop import NestedEventLoopRule
+from .fastt005_blocking_file_io import BlockingFileIORule
+from .fastt006_sync_subprocess import SyncSubprocessRule
+
+__all__ = [
+    "BlockingFileIORule",
+    "DbSessionInAsyncRule",
+    "NestedEventLoopRule",
+    "NoAwaitInAsyncRule",
+    "SyncBlockingIORule",
+    "SyncSubprocessRule",
+]

fastapi_therapist-0.1.0/src/fastapi_doctor/rules/async_sync/fastt001_sync_blocking_io.py

@@ -0,0 +1,80 @@
+import ast
+
+from fastapi_doctor.rules.base import (
+    Rule,
+    register_rule,
+    is_fastapi_endpoint,
+    get_call_sig,
+    collect_threadpool_wrappers,
+    is_inside_wrapper,
+)
+from fastapi_doctor.models import Diagnostic, RuleDefinition, Severity
+
+BLOCKING_CALLS = {
+    ("requests", "get"),
+    ("requests", "post"),
+    ("requests", "put"),
+    ("requests", "patch"),
+    ("requests", "delete"),
+    ("requests", "head"),
+    ("requests", "request"),
+    ("requests", "Session"),
+    ("urllib.request", "urlopen"),
+    ("time", "sleep"),
+    ("httpx", "get"),
+    ("httpx", "post"),
+    ("httpx", "put"),
+    ("httpx", "delete"),
+    ("httpx", "Client"),
+}
+
+
+@register_rule
+class SyncBlockingIORule(Rule):
+    """Detect synchronous blocking IO in async FastAPI endpoints (FASTT001)."""
+
+    @property
+    def definition(self) -> RuleDefinition:
+        return RuleDefinition(
+            id="fastapi-doctor/FASTT001",
+            severity=Severity.ERROR,
+            description="async def endpoint calling synchronous blocking IO (requests.get, urllib, time.sleep, sync httpx) without run_in_threadpool",
+            recommendation="Wrap blocking IO in asyncio.to_thread() or use async alternatives (httpx.AsyncClient, asyncio.sleep, etc.)",
+        )
+
+    def check(self, tree: ast.Module, file_path: str, source: str) -> list[Diagnostic]:
+        diagnostics = []
+
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.AsyncFunctionDef):
+                continue
+
+            method_name = is_fastapi_endpoint(node)
+            if method_name is None:
+                continue
+
+            wrappers = collect_threadpool_wrappers(node)
+
+            for child in ast.walk(node):
+                if not isinstance(child, ast.Call):
+                    continue
+
+                call_sig = get_call_sig(child)
+                if call_sig is None:
+                    continue
+
+                if call_sig in BLOCKING_CALLS:
+                    if not is_inside_wrapper(child, wrappers):
+                        diagnostics.append(
+                            Diagnostic(
+                                severity=self.definition.severity,
+                                file_path=file_path,
+                                rule=self.definition.id,
+                                message=f"Blocking call '{call_sig[0]}.{call_sig[1]}()' inside async endpoint '{node.name}' without asyncio.to_thread()",
+                                line=child.lineno,
+                                column=child.col_offset,
+                                help=self.definition.recommendation,
+                            )
+                        )
+
+        return diagnostics

fastapi_therapist-0.1.0/src/fastapi_doctor/rules/async_sync/fastt002_db_session_in_async.py

@@ -0,0 +1,158 @@
+import ast
+
+from fastapi_doctor.rules.base import (
+    Rule,
+    register_rule,
+    is_fastapi_endpoint,
+    collect_threadpool_wrappers,
+    is_inside_wrapper,
+)
+from fastapi_doctor.models import Diagnostic, RuleDefinition, Severity
+
+DB_SESSION_METHODS = {
+    "execute",
+    "commit",
+    "rollback",
+    "query",
+    "flush",
+    "refresh",
+    "merge",
+    "delete",
+    "bulk_save_objects",
+    "bulk_insert_mappings",
+    "scalars",
+    "scalar",
+}
+
+ASYNC_RESULT_METHODS = {
+    "scalars",
+    "scalar",
+    "fetchone",
+    "fetchmany",
+    "fetchall",
+    "all",
+    "first",
+    "one",
+    "one_or_none",
+}
+
+
+@register_rule
+class DbSessionInAsyncRule(Rule):
+    """Detect synchronous SQLAlchemy session calls in async FastAPI endpoints (FASTT002)."""
+
+    @property
+    def definition(self) -> RuleDefinition:
+        return RuleDefinition(
+            id="fastapi-doctor/FASTT002",
+            severity=Severity.ERROR,
+            description="Synchronous SQLAlchemy session call inside async endpoint — use AsyncSession instead",
+            recommendation="Use AsyncSession with await (e.g. await session.execute()) or wrap in asyncio.to_thread()",
+        )
+
+    def check(self, tree: ast.Module, file_path: str, source: str) -> list[Diagnostic]:
+        diagnostics = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.AsyncFunctionDef):
+                continue
+            if is_fastapi_endpoint(node) is None:
+                continue
+            diagnostics.extend(self._check_single(node, file_path))
+        return diagnostics
+
+    def check_function(
+        self, func_node: ast.FunctionDef | ast.AsyncFunctionDef, file_path: str
+    ) -> list[Diagnostic]:
+        """Check a resolved function body (used by import trace pass)."""
+        return self._check_single(func_node, file_path)
+
+    def _check_single(
+        self, func_node: ast.FunctionDef | ast.AsyncFunctionDef, file_path: str
+    ) -> list[Diagnostic]:
+        """Core check: find sync DB calls in a function body."""
+        diagnostics = []
+        wrappers = collect_threadpool_wrappers(func_node)
+
+        decorator_descendants = self._collect_decorator_descendants(func_node)
+        awaited_descendants = self._collect_awaited_descendants(func_node)
+        inner_func_descendants = self._collect_inner_func_descendants(func_node)
+
+        for child in ast.walk(func_node):
+            if not isinstance(child, ast.Call):
+                continue
+            if not isinstance(child.func, ast.Attribute):
+                continue
+            if (
+                child in decorator_descendants
+                or child in awaited_descendants
+                or child in inner_func_descendants
+            ):
+                continue
+
+            method = child.func.attr
+            if method not in DB_SESSION_METHODS:
+                continue
+            if method in ASYNC_RESULT_METHODS:
+                continue
+            if self._is_on_async_session(child):
+                continue
+            if is_inside_wrapper(child, wrappers):
+                continue
+
+            diagnostics.append(
+                Diagnostic(
+                    severity=self.definition.severity,
+                    file_path=file_path,
+                    rule=self.definition.id,
+                    message=f"Synchronous DB call '{method}()' inside async endpoint '{func_node.name}' — use await with AsyncSession",
+                    line=child.lineno,
+                    column=child.col_offset,
+                    help=self.definition.recommendation,
+                )
+            )
+
+        return diagnostics
+
+    KNOWN_ASYNC_VARS = {"async_session", "async_db", "asession", "async_conn"}
+
+    def _is_on_async_session(self, node: ast.Call) -> bool:
+        if isinstance(node.func, ast.Attribute):
+            if isinstance(node.func.value, ast.Name):
+                base_name = node.func.value.id.lower()
+                if any(name in base_name for name in self.KNOWN_ASYNC_VARS):
+                    return True
+                if base_name.startswith("async_"):
+                    return True
+        return False
+
+    def _collect_decorator_descendants(
+        self, func_node: ast.FunctionDef | ast.AsyncFunctionDef
+    ) -> set[ast.AST]:
+        descendants: set[ast.AST] = set()
+        for decorator in func_node.decorator_list:
+            for desc in ast.walk(decorator):
+                descendants.add(desc)
+        return descendants
+
+    def _collect_awaited_descendants(
+        self, func_node: ast.FunctionDef | ast.AsyncFunctionDef
+    ) -> set[ast.AST]:
+        descendants: set[ast.AST] = set()
+        for node in ast.walk(func_node):
+            if isinstance(node, ast.Await):
+                for desc in ast.walk(node):
+                    descendants.add(desc)
+        return descendants
+
+    def _collect_inner_func_descendants(
+        self, func_node: ast.FunctionDef | ast.AsyncFunctionDef
+    ) -> set[ast.AST]:
+        descendants: set[ast.AST] = set()
+        for node in ast.walk(func_node):
+            if (
+                isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+                and node is not func_node
+            ):
+                for desc in ast.walk(node):
+                    descendants.add(desc)
+        return descendants