richapi 0.3.1__tar.gz → 0.4.0__tar.gz

{richapi-0.3.1 → richapi-0.4.0}/.github/workflows/main.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
       fail-fast: false
     steps:
       - uses: actions/checkout@v4

richapi-0.4.0/.github/workflows/on-release-main.yml

@@ -0,0 +1,34 @@
+name: release-main
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Check version matches the release tag
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(uv version --short)"
+          init="$(sed -n 's/^__version__ = "\(.*\)"/\1/p' richapi/__version__.py)"
+          if [ "$tag" != "$pkg" ] || [ "$tag" != "$init" ]; then
+            echo "::error::Release tag is $tag but pyproject.toml has $pkg and __version__.py has $init. Bump both before releasing."
+            exit 1
+          fi
+
+      # rye publish bundles an old twine that rejects current hatchling metadata (2.4+).
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish --token "$PYPI_TOKEN"
+        env:
+          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}

{richapi-0.3.1 → richapi-0.4.0}/PKG-INFO

@@ -1,13 +1,13 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.5
 Name: richapi
-Version: 0.3.1
+Version: 0.4.0
 Summary: Find HTTPExceptions and turn them into documented responses!
 Project-URL: repository, https://github.com/ManiMozaffar/richapi
 Project-URL: Homepage, https://github.com/ManiMozaffar/richapi
 Project-URL: Documentation, https://github.com/ManiMozaffar/richapi
 Project-URL: Source, https://github.com/ManiMozaffar/richapi
 License-Expression: MIT
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Requires-Dist: fastapi>=0.105
 Requires-Dist: typer>=0.12
 Description-Content-Type: text/markdown

richapi-0.4.0/benchmarks/bench.py

@@ -0,0 +1,59 @@
+"""Benchmark richapi on a generated project.
+
+Usage:
+    uv run python benchmarks/bench.py [--size small|medium|large] [--out schema.json]
+
+Runs in a fresh process each time so no state leaks between runs.
+"""
+
+import argparse
+import importlib
+import json
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).parent))
+from generate_project import generate  # noqa: E402
+
+SIZES: dict[str, dict[str, Any]] = {
+    "small": dict(n_services=5, n_funcs=20, n_routers=4, n_endpoints=5),
+    "medium": dict(n_services=30, n_funcs=40, n_routers=20, n_endpoints=15),
+    "large": dict(n_services=80, n_funcs=80, n_routers=60, n_endpoints=20),
+}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--size", choices=SIZES, default="medium")
+    parser.add_argument("--out", type=Path, default=None)
+    parser.add_argument("--repeat", type=int, default=1)
+    args = parser.parse_args()
+
+    with tempfile.TemporaryDirectory() as tmp:
+        pkg = generate(Path(tmp), **SIZES[args.size])
+        sys.path.insert(0, tmp)
+        app = importlib.import_module(f"{pkg}.main").app
+
+        from richapi.exc_parser.openapi import compile_openapi_from_fastapi
+
+        n_routes = len(app.routes)
+        timings = []
+        schema = None
+        for _ in range(args.repeat):
+            start = time.perf_counter()
+            schema = compile_openapi_from_fastapi(app, pkg)
+            timings.append(time.perf_counter() - start)
+
+    print(
+        f"size={args.size} routes={n_routes} "
+        f"best={min(timings):.3f}s runs={[round(t, 3) for t in timings]}"
+    )
+    if args.out:
+        args.out.write_text(json.dumps(schema, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()

richapi-0.4.0/benchmarks/compare.py

@@ -0,0 +1,82 @@
+"""Compare richapi from a git ref (default: main) against the working tree.
+
+Usage:
+    uv run python benchmarks/compare.py [--ref main] [--size medium]
+
+Checks out <ref> into a temporary git worktree, runs bench.py with each
+version on the same generated project, and verifies both produce the
+exact same OpenAPI schema.
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+BENCH = Path(__file__).resolve().parent / "bench.py"
+
+
+def run(richapi_root: Path, size: str, out: Path, repeat: int) -> str:
+    env = {**os.environ, "PYTHONPATH": str(richapi_root)}
+    cmd = [sys.executable, str(BENCH), "--size", size, "--out", str(out)]
+    cmd += ["--repeat", str(repeat)]
+    return subprocess.run(
+        cmd, env=env, check=True, capture_output=True, text=True
+    ).stdout.strip()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--ref", default="main")
+    parser.add_argument("--size", default="medium")
+    parser.add_argument("--repeat", type=int, default=1)
+    args = parser.parse_args()
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp = Path(tmp)
+        worktree = tmp / "ref"
+        subprocess.run(
+            [
+                "git",
+                "-C",
+                str(ROOT),
+                "worktree",
+                "add",
+                "-q",
+                "--detach",
+                str(worktree),
+                args.ref,
+            ],
+            check=True,
+        )
+        try:
+            print(
+                f"{args.ref:>10}: {run(worktree, args.size, tmp / 'ref.json', args.repeat)}"
+            )
+            print(
+                f"{'current':>10}: {run(ROOT, args.size, tmp / 'cur.json', args.repeat)}"
+            )
+            same = (tmp / "ref.json").read_text() == (tmp / "cur.json").read_text()
+            print("schemas identical" if same else "SCHEMAS DIFFER")
+        finally:
+            subprocess.run(
+                [
+                    "git",
+                    "-C",
+                    str(ROOT),
+                    "worktree",
+                    "remove",
+                    "--force",
+                    str(worktree),
+                ],
+                check=True,
+            )
+    if not same:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

richapi-0.4.0/benchmarks/generate_project.py

@@ -0,0 +1,172 @@
+"""Generate a synthetic, large FastAPI project to benchmark richapi's analysis.
+
+The layout mimics a real service: exceptions, many service modules full of
+helpers/classes calling each other, shared dependencies and routers.
+"""
+
+import random
+import textwrap
+from pathlib import Path
+
+
+def _w(path: Path, body: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(textwrap.dedent(body).lstrip())
+
+
+def generate(
+    root: Path,
+    pkg: str = "bench_app",
+    n_services: int = 30,
+    n_funcs: int = 40,
+    n_routers: int = 20,
+    n_endpoints: int = 15,
+    seed: int = 0,
+) -> str:
+    rnd = random.Random(seed)
+    base = root / pkg
+    _w(base / "__init__.py", "")
+    _w(base / "services" / "__init__.py", "")
+    _w(base / "routes" / "__init__.py", "")
+
+    exc_lines = [
+        "from fastapi import HTTPException",
+        "from pydantic.dataclasses import dataclass",
+        "from richapi import BaseHTTPException, RichHTTPException",
+        "",
+    ]
+    for i in range(40):
+        exc_lines += [
+            "@dataclass",
+            f"class Rich{i}(RichHTTPException):",
+            f'    """Rich error {i}"""',
+            f"    status_code = {400 + i % 30}",
+            f"    field_{i}: int = 0",
+            "",
+            f"class Plain{i}(HTTPException): ...",
+            "",
+            f"class Base{i}(BaseHTTPException):",
+            f"    status_code = {400 + (i * 7) % 30}",
+            f'    detail = "base error {i}"',
+            "",
+        ]
+    _w(base / "exceptions.py", "\n".join(exc_lines) + "\n")
+
+    for s in range(n_services):
+        lines = [
+            "from fastapi import HTTPException, status",
+            f"from {pkg} import exceptions as E",
+            f"from {pkg}.exceptions import Rich{s % 40}, Plain{s % 40}",
+        ]
+        if s > 0:
+            lines.append(f"from {pkg}.services import svc_{s - 1} as prev")
+        lines.append("")
+        for f in range(n_funcs):
+            kind = rnd.randrange(5)
+            lines.append(f"def helper_{f}(x: int = 0):")
+            if kind == 0:
+                lines.append(f"    raise Rich{s % 40}()")
+            elif kind == 1:
+                lines.append(
+                    f'    raise Plain{s % 40}(status_code={400 + f % 30}, detail="svc {s} helper {f}")'
+                )
+            elif kind == 2:
+                lines.append(f"    exc = E.Base{(s + f) % 40}()")
+                lines.append("    raise exc")
+            elif kind == 3 and f > 0:
+                lines.append(f"    helper_{rnd.randrange(f)}(x)")
+                lines.append(
+                    '    raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="missing")'
+                )
+            else:
+                lines.append("    total = 0")
+                lines.append("    for i in range(x):")
+                lines.append("        total += i")
+                lines.append("    return total")
+            if s > 0 and rnd.random() < 0.3:
+                lines.append(f"    prev.helper_{rnd.randrange(n_funcs)}(x)")
+            lines.append("")
+        # filler to make modules realistically large
+        for f in range(n_funcs):
+            lines += [
+                f"def _private_{f}(a, b, c=None):",
+                '    """Some unrelated code that richapi has to parse anyway."""',
+                "    data = {'a': a, 'b': b, 'c': c}",
+                "    return [v for v in data.values() if v is not None]",
+                "",
+            ]
+        lines += [
+            f"class Repo{s}:",
+            "    def get(self, x):",
+            f"        helper_{rnd.randrange(n_funcs)}(x)",
+            "        return x",
+            "",
+            f"class Service{s}:",
+            f"    repo: Repo{s}",
+            "",
+            "    def __init__(self):",
+            f"        self.repo = Repo{s}()",
+            f"        helper_{rnd.randrange(n_funcs)}()",
+            "",
+        ]
+        for m in range(10):
+            lines += [
+                f"    def method_{m}(self, x: int):",
+                f"        helper_{rnd.randrange(n_funcs)}(x)",
+                "        self.repo.get(x)",
+                "        return self",
+                "",
+            ]
+        _w(base / "services" / f"svc_{s}.py", "\n".join(lines) + "\n")
+
+    _w(
+        base / "deps.py",
+        f"""
+        import fastapi
+        import fastapi.security
+        from {pkg}.services import svc_0
+
+        bearer = fastapi.security.HTTPBearer()
+
+        def get_token(token=fastapi.Depends(bearer)):
+            svc_0.helper_0()
+            return token
+
+        def get_user(token: str = fastapi.Depends(get_token)):
+            if not token:
+                raise fastapi.HTTPException(status_code=401, detail="unauthorized")
+            return token
+        """,
+    )
+
+    for r in range(n_routers):
+        lines = [
+            "from fastapi import APIRouter, Depends, HTTPException",
+            f"from {pkg}.deps import get_user",
+        ]
+        used = sorted({rnd.randrange(n_services) for _ in range(4)})
+        for s in used:
+            lines.append(f"from {pkg}.services import svc_{s}")
+            lines.append(f"from {pkg}.services.svc_{s} import Service{s}")
+        lines += ["", "router = APIRouter()", ""]
+        for e in range(n_endpoints):
+            s = rnd.choice(used)
+            lines += [
+                f'@router.get("/r{r}/e{e}")',
+                f"async def endpoint_{r}_{e}(x: int, user: str = Depends(get_user)):",
+                f"    svc = Service{s}()",
+                f"    svc.method_{rnd.randrange(10)}(x).method_{rnd.randrange(10)}(x)",
+                f"    svc_{s}.helper_{rnd.randrange(n_funcs)}(x)",
+                "    if x < 0:",
+                f'        raise HTTPException(status_code={400 + e % 20}, detail="route {r} {e}")',
+                "    return {'ok': True}",
+                "",
+            ]
+        _w(base / "routes" / f"r_{r}.py", "\n".join(lines) + "\n")
+
+    lines = ["from fastapi import FastAPI"]
+    lines += [f"from {pkg}.routes import r_{r}" for r in range(n_routers)]
+    lines += ["", "app = FastAPI()"]
+    lines += [f"app.include_router(r_{r}.router)" for r in range(n_routers)]
+    _w(base / "main.py", "\n".join(lines) + "\n")
+    return pkg

{richapi-0.3.1 → richapi-0.4.0}/docs/advance.md

@@ -49,3 +49,27 @@ app = FastAPI()
 # add your routers ....
 app.openapi = enrich_openapi(app, ["your_module_name", "some-other-package"])
 ```
+
+### Finding exceptions in specific API functions of FastAPI
+
+If you want to limit the search of exceptions to specific functions, you can pass the list of functions to the `find_exceptions_in_api_functions` function.
+
+```python
+from richapi import find_exceptions_in_api_functions, BaseHTTPException
+from fastapi import FastAPI
+
+app = FastAPI()
+
+class NotFoundException(BaseHTTPException):
+    status_code = 404
+    detail: str = "Item not found"
+
+@app.get("/items/{item_id}")
+async def read_item(item_id: int):
+    if item_id != 42:
+        raise NotFoundException()
+    return {"item_id": item_id}
+
+exceptions = find_exceptions_in_api_functions(funcs=[read_item], fastapi_app=app)
+print(exceptions)  # {NotFoundException}
+```

{richapi-0.3.1 → richapi-0.4.0}/makefile

@@ -14,6 +14,9 @@ test: ## Test the code with pytest
 	@echo "🚀 Testing code: Running pytest"
 	uv run pytest
 
+.PHONY: bench
+bench: ## Benchmark analysis speed against main on a generated project
+	uv run python benchmarks/compare.py --ref main --size medium
 
 .PHONY: docs
 docs:  ## Build and serve the documentation

{richapi-0.3.1 → richapi-0.4.0}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "richapi"
-version = "0.3.1"
+version = "0.4.0"
 description = "Find HTTPExceptions and turn them into documented responses!"
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 dependencies = ["typer>=0.12", "fastapi>=0.105"]
 license = 'MIT'
 
@@ -19,6 +19,7 @@ build-backend = "hatchling.build"
 
 [tool.pytest.ini_options]
 asyncio_default_fixture_loop_scope = "session"
+addopts = "--log-level=DEBUG -v"
 
 [tool.pyright]
 typeCheckingMode = "standard"
@@ -35,7 +36,7 @@ packages = ["richapi"]
 [tool.uv]
 dev-dependencies = [
     "ruff>=0.6.9",
-    "pyright>=1.1.384",
+    "pyright>=1.1.397",
     "rich>=13.9.2",
     "pytest>=8.3.3",
     "pytest-asyncio>=0.24.0",

{richapi-0.3.1 → richapi-0.4.0}/richapi/__init__.py

@@ -1,5 +1,9 @@
 from richapi.exc_parser.handler import add_exc_handler
-from richapi.exc_parser.openapi import enrich_openapi, load_openapi
+from richapi.exc_parser.openapi import (
+    enrich_openapi,
+    find_exceptions_in_api_functions,
+    load_openapi,
+)
 from richapi.exc_parser.protocol import BaseHTTPException, RichHTTPException
 
 __all__ = [
@@ -8,4 +12,5 @@ __all__ = [
     "BaseHTTPException",
     "RichHTTPException",
     "add_exc_handler",
+    "find_exceptions_in_api_functions",
 ]

richapi-0.4.0/richapi/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"