richapi 0.1.0__py3-none-any.whl

richapi/__init__.py

@@ -0,0 +1,4 @@
+from richapi.exc_parser.openapi import enrich_openapi, load_openapi
+from richapi.exc_parser.protocol import BaseHTTPException
+
+__all__ = ["enrich_openapi", "load_openapi", "BaseHTTPException"]

richapi/__version__.py

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

richapi/cli.py

@@ -0,0 +1,87 @@
+import importlib
+import json
+from pathlib import Path
+from typing import Annotated, Optional, Union
+
+import typer
+from fastapi import FastAPI
+
+from richapi.exc_parser.openapi import compile_openapi_from_fastapi
+
+app = typer.Typer()
+
+
+def dynamic_import(module_name: str, attribute: Optional[str] = None):
+    """
+    Dynamically import a module and optionally get an attribute from it.
+    """
+    try:
+        module = importlib.import_module(module_name)
+        if attribute:
+            return getattr(module, attribute)
+        return module
+    except ModuleNotFoundError:
+        raise typer.BadParameter(f"Module '{module_name}' not found.")
+    except AttributeError:
+        raise typer.BadParameter(
+            f"Attribute '{attribute}' not found in module '{module_name}'."
+        )
+
+
+@app.command()
+def compile(
+    fastapi_path: Annotated[
+        str,
+        typer.Argument(help="The FastAPI application path."),
+    ],
+    target_path: Annotated[
+        Union[Path, None],
+        typer.Argument(help="The target path to save the OpenAPI schema."),
+    ] = None,
+    module_to_compile: Annotated[
+        Optional[str],
+        typer.Argument(help="The module to look for the FastAPI application."),
+    ] = None,
+):
+    """
+    Compile an OpenAPI schema from a FastAPI application, extending all possible FastAPI exceptions to the OpenAPI schema.
+    Compile the module and attribute using the format {module_name}:{attribute}.
+    """
+    if ":" not in fastapi_path:
+        raise typer.BadParameter(
+            "Invalid format. Please use the format {module}.{module}:{app}."
+        )
+
+    if not target_path:
+        target_path = Path.cwd() / "openapi.json"
+
+    module_name, attribute = fastapi_path.split(":")
+
+    if module_to_compile is None:
+        module_to_compile = module_name.split(".")[0]
+
+    app_object = dynamic_import(module_name, attribute)
+    if not isinstance(app_object, FastAPI):
+        raise typer.BadParameter(
+            f"Expected FastAPI object, but got `{type(app_object).__name__}`."
+        )
+    typer.echo(
+        f"Successfully accessed '{attribute}' in module '{module_name}', compiling OpenAPI..."
+    )
+
+    openapi_json = compile_openapi_from_fastapi(app_object, module_to_compile)
+
+    with open(target_path, "w") as file:
+        file.write(json.dumps(openapi_json, indent=2))
+
+    typer.echo(f"OpenAPI schema saved to '{target_path}'")
+    return
+
+
+@app.command(name="test-compile")
+def test():
+    typer.echo("Hello, World!")
+
+
+if __name__ == "__main__":
+    app()

richapi/exc_parser/__init__.py

@@ -0,0 +1,4 @@
+from richapi.exc_parser.openapi import enrich_openapi, load_openapi
+from richapi.exc_parser.protocol import BaseHTTPException, HTTPExceptionSchema
+
+__all__ = ["enrich_openapi", "load_openapi", "BaseHTTPException", "HTTPExceptionSchema"]

richapi/exc_parser/compiler.py

@@ -0,0 +1,495 @@
+import ast
+import builtins
+import inspect
+import logging
+import sysconfig
+import typing
+from functools import lru_cache
+from importlib.util import find_spec
+from typing import Callable, List, NewType, Optional, Tuple, Union
+
+logger = logging.getLogger(__name__)
+
+
+def not_supported(
+    value: typing.NoReturn,
+) -> typing.NoReturn: ...  # don't raise any exceptions just type checking
+
+
+# Extending this list will raise typing checks on all codes.
+# To support a new node, just add it to list and resolve all typing checks.
+
+SupportedAstNodes = Union[
+    ast.Call,  # Function call
+    ast.FunctionDef,  # Function definition
+    ast.AsyncFunctionDef,  # Async function definition
+    ast.ClassDef,  # Class definition
+    ast.Raise,  # Raise statement
+    ast.Assign,  # Assignment statement
+    ast.Attribute,  # Attribute access
+    ast.Name,  # Variable name
+    ast.Await,  # Await expression
+]
+
+NodeIdentifier = NewType("NodeIdentifier", str)
+"""Branded type that represents a node identifier that can be used a key in a dictionary."""
+
+
+def get_node_identifier(node: ast.Name) -> NodeIdentifier:
+    """Get the identifier of the given node."""
+
+    return NodeIdentifier(node.id)
+
+
+def is_in_module(module: str, target_modules: list[str]) -> bool:
+    """
+    Module is like 'module.submodule.Class.method'
+    target modules are like ['module.submodule', 'module.submodule2']
+    """
+    if module == "__main__":  # always look into main module
+        return True
+
+    if "." not in module:
+        module = module + "."  # to match the module.* pattern
+
+    for target in target_modules:
+        if module.startswith(target):
+            return True
+    return False
+
+
+def find_explicit_exceptions(
+    func: Callable,
+    target_modules: Union[list[str], str],
+    should_search_module_pred: Union[Callable[[str], bool], None] = None,
+) -> List[Tuple[Optional[type[Exception]], ast.Raise]]:
+    """
+    Analyze the given function and find all explicitly raised exceptions,
+    including those in nested functions and class methods.
+
+    Returns:
+        A list of tuples where each tuple contains:
+            - The exception class (or None if it couldn't be resolved)
+            - The ast.Raise node
+    """
+
+    if isinstance(target_modules, str):
+        target_modules = [target_modules]
+
+    if should_search_module_pred is None:
+
+        def should_search_module_pred_func(target):
+            return is_in_module(target, target_modules)
+
+        should_search_module_pred = should_search_module_pred_func
+
+    try:
+        source = inspect.getsource(func)
+    except (OSError, TypeError):
+        raise Exception(func)
+
+    tree = ast.parse(source)
+
+    return _find_explicit_expection_recursively(func, tree, should_search_module_pred)
+
+
+def _find_explicit_expection_recursively(
+    func_obj: Callable,
+    expr: ast.AST,
+    to_filter_predicate: Callable[[str], bool],
+):
+    if func_obj in ExceptionFinder.visited:
+        return []
+
+    module = inspect.getmodule(func_obj)
+    if module and is_stdlib(module.__name__):
+        return []
+
+    if module and to_filter_predicate(module.__name__) is False:
+        return []
+
+    finder = ExceptionFinder(func_obj, to_filter_predicate)
+    finder.visit(expr)
+    ExceptionFinder.visited.add(func_obj)
+    return finder.exceptions
+
+
+def _find_in_module(module: ast.Module, predicate: Callable[[ast.AST], bool]):
+    for node in ast.walk(module):
+        if predicate(node):
+            return node
+    return None
+
+
+def _find_method_node_in_cls(cls: ast.ClassDef, method_name: str):
+    for node in cls.body:
+        if isinstance(node, ast.FunctionDef) and node.name == method_name:
+            return node
+    return None
+
+
+def _resolve_full_attribute_path(node: ast.AST) -> Union[str, None]:
+    """
+    Reconstruct the full attribute name from an AST node, handling nested attributes and calls.
+
+    Examples:
+        sa.select(...).where(...) -> "sa.select.where"
+        obj.method1().method2 -> "obj.method1.method2"
+        module.submodule.Class.method -> "module.submodule.Class.method"
+    """
+    names: list[str] = []
+
+    def recurse(n):
+        if isinstance(n, ast.Attribute):
+            names.append(n.attr)
+            recurse(n.value)
+        elif isinstance(n, ast.Call):
+            recurse(n.func)
+        elif isinstance(n, ast.Name):
+            names.append(n.id)
+        else:
+            # Unsupported node type encountered
+            pass
+
+    recurse(node)
+
+    if names:
+        # The names are collected in reverse order, so reverse them back
+        return ".".join(reversed(names))
+
+    return None
+
+
+def _resolve_function_from_call_node(
+    call_node: ast.Call,
+    func_globals: dict,
+    func: Callable,
+    assignments: dict[NodeIdentifier, str],
+):
+    """
+    Attempt to resolve the function object from a call node.
+    Handles both simple function calls and method calls.
+    """
+    node = call_node.func
+
+    if isinstance(node, ast.Name):
+        # Simple function call: func()
+        value = func_globals.get(node.id, None)
+
+        if value is None:
+            value = getattr(builtins, node.id, None)
+
+        if value is None:
+            logger.debug(f"Function '{node.id}' not found in {func.__name__}")
+
+        return value
+
+    elif isinstance(node, ast.Attribute):
+        attr_chain = _resolve_full_attribute_path(node)
+        if attr_chain is None:
+            logger.debug(
+                f"Failed to get full attribute name: {ast.dump(node)} in {func.__name__}"
+            )
+            return None
+
+        try:
+            parts = attr_chain.split(".")
+            parent_part = parts[0]
+
+            parent_attr = func_globals.get(parent_part, None)
+
+            if parent_attr is None:
+                if parent_part in func.__annotations__:
+                    return func.__annotations__[parent_part]
+
+                parent_attr = getattr(builtins, parent_part, None)
+
+            if parent_attr is None:
+                node_id = NodeIdentifier(parent_part)
+                parent_attr = assignments.get(node_id, None)
+
+            if parent_attr is None:
+                if (
+                    parent_part == "self"
+                ):  # don't need to log -> we already know this is class
+                    return None
+
+                print(attr_chain, parent_part)
+                logger.debug(
+                    f"Failed to resolve parent attribute {parent_part} for parts {attr_chain}. Chain: {ast.dump(node)} for func {func.__name__}"
+                )
+                return None
+
+            for attr in parts[1:]:
+                try:
+                    obj = getattr(parent_attr, attr, None)
+                except Exception:
+                    break
+
+                return obj
+
+        except Exception:
+            logger.exception(f"Failed to resolve attribute chain: {attr_chain}")
+            return None
+
+
+def _extract_node_name(
+    node: SupportedAstNodes, assignments: dict[NodeIdentifier, str]
+) -> Optional[str]:
+    """
+    Extract the exception name a node recursively.
+    """
+    if isinstance(node, ast.Call):
+        return _extract_node_name(
+            typing.cast(SupportedAstNodes, node.func), assignments
+        )
+    elif isinstance(node, ast.Name):
+        var_name = get_node_identifier(node)
+        return assignments.get(var_name, var_name)
+    elif isinstance(node, ast.Attribute):
+        return _resolve_full_attribute_path(node)
+
+    elif isinstance(node, ast.Await):
+        return _extract_node_name(
+            typing.cast(SupportedAstNodes, node.value), assignments
+        )
+
+    elif isinstance(
+        node,
+        (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Raise, ast.Assign),
+    ):
+        ...  # not supported -> we cannot resolve the exception name
+
+    else:
+        not_supported(node)
+        return None
+
+
+def _exctact_type(var_tyep: str, func_globals: dict) -> Optional[type]:
+    """
+    Attempt to resolve the exception name to an actual exception class.
+    """
+    try:
+        exc_type = eval(var_tyep, func_globals)
+        if isinstance(exc_type, type) and issubclass(exc_type, BaseException):
+            return exc_type
+    except BaseException:
+        return None
+
+    try:
+        # Fallback to builtins
+        return getattr(builtins, var_tyep, None)
+    except Exception:
+        logger.exception(f"Failed to resolve variable type: {var_tyep}")
+
+
+@lru_cache
+def is_stdlib(module_name: str) -> bool:
+    """Check if a given module is part of the Python standard library."""
+    try:
+        module_spec = find_spec(module_name)
+    except Exception:
+        return False
+
+    if module_spec is None or module_spec.origin is None:
+        return False
+    std_lib_paths = sysconfig.get_paths()["stdlib"]
+    return module_spec.origin.startswith(std_lib_paths)
+
+
+class ExceptionFinder(ast.NodeVisitor):
+    visited: set[Callable] = set()
+
+    def __init__(
+        self, func: Callable, should_search_module_pred: Callable[[str], bool]
+    ):
+        self.exceptions: List[Tuple[Optional[type[Exception]], ast.Raise]] = []
+        self.assignments: dict[NodeIdentifier, str] = {}
+        self.func = func
+        self.func_globals = func.__globals__
+        self.should_search_module_pred = should_search_module_pred
+        logger.info(f"Analyzing function {func.__name__}")
+
+    def visit_Assign(self, node):
+        """
+        Track assignments to variables that are exceptions or exception instances.
+        Since we don't know the type of the variable, we just store the name.
+
+        Handled scenarios:
+            - Case 1: Name assigment
+                exc = ValueError("An error occurred")
+                raise exc
+
+            - Other cases:
+                They should be handled by raise statement visitor.
+                They are assigned to a variable and assuming we visit and resolve it, should be enough.
+                But sometimes it's impossible to resolve the exception name from these nodes.
+
+                Example:
+
+                    exc_callback = lambda: ValueError("An error occurred")
+                    raise exc_callback()
+        """
+        value = typing.cast(SupportedAstNodes, node.value)
+        targets = typing.cast(list[SupportedAstNodes], node.targets)
+
+        for target in targets:
+            if isinstance(target, ast.Name):
+                var_identifier = get_node_identifier(target)
+                var_name = _extract_node_name(value, self.assignments)
+                if var_name is not None:
+                    self.assignments[var_identifier] = var_name
+
+                else:
+                    # no need to log here. it would be very spammy
+                    # basically anything can happen here because, and won't be very unexpected
+                    # imagine a lambda function assigned to a variable and raised later.
+                    # so we only support whatever cases handled by `_extract_node_name`
+                    ...
+
+            elif isinstance(
+                target,
+                (
+                    ast.Call,
+                    ast.FunctionDef,
+                    ast.AsyncFunctionDef,
+                    ast.ClassDef,
+                    ast.Raise,
+                    ast.Assign,
+                    ast.Attribute,
+                    ast.Await,
+                ),
+            ):
+                pass  # should be handled by raise statement visitor
+
+            else:
+                not_supported(target)
+
+        self.generic_visit(node)
+
+    def visit_Raise(self, node):
+        """
+        Handle raise statements and collect exceptions.
+        """
+        exc = node.exc
+        if exc is None:
+            # Could not resolve exception name -> maybe just using 'raise' without an exception
+            # this edge case basically can raise anything
+            logger.debug("Please don't use 'raise' without declaring what to raise")
+            self.exceptions.append((None, node))
+            self.generic_visit(node)
+            return
+
+        exc_variable_name = _extract_node_name(
+            typing.cast(SupportedAstNodes, exc), self.assignments
+        )
+        if exc_variable_name is None:
+            # We are raising an exception that is assigned to a variable we don't know
+            # Maybe global variable ?
+            self.exceptions.append((None, node))
+            self.generic_visit(node)
+            logger.debug(f"Failed to get exception name: {ast.dump(node)}")
+            return
+
+        exc_type = _exctact_type(exc_variable_name, self.func_globals)
+
+        if exc_type:
+            self.exceptions.append((exc_type, node))
+
+        self.generic_visit(node)
+        return
+
+    def visit_Call(self, node):
+        """
+        Handle function calls and recursively analyze called functions.
+        """
+        func_obj = _resolve_function_from_call_node(
+            node, self.func_globals, self.func, self.assignments
+        )
+        if func_obj and inspect.isfunction(func_obj):
+            module = inspect.getmodule(func_obj)
+            if not module:
+                self.generic_visit(node)
+                return
+
+            if (
+                is_stdlib(module.__name__)
+                or self.should_search_module_pred(module.__name__) is False
+            ):
+                self.generic_visit(node)
+                return
+
+            source = inspect.getsource(module)
+            tree = ast.parse(source)
+
+            founded_func = _find_in_module(
+                tree,
+                lambda n: (
+                    isinstance(n, ast.AsyncFunctionDef)
+                    or isinstance(n, ast.FunctionDef)
+                )
+                and n.name == func_obj.__name__,
+            )
+            if founded_func:
+                excs = _find_explicit_expection_recursively(
+                    func_obj, founded_func, self.should_search_module_pred
+                )
+                self.exceptions.extend(excs)
+            else:
+                logger.debug(
+                    f"Failed to find function {func_obj.__name__} in module {module.__name__}"
+                )
+
+        self.generic_visit(node)
+        return
+
+    def visit_Attribute(self, node):
+        node_value = typing.cast(SupportedAstNodes, node.value)
+
+        if isinstance(node_value, ast.Name):
+            caller_node_name = self.assignments.get(get_node_identifier(node_value))
+            if not caller_node_name:
+                self.generic_visit(node)
+                return
+
+            try:
+                caller_type = _exctact_type(caller_node_name, self.func_globals)
+            except Exception:
+                logger.critical(
+                    f"Failed to resolve attribute chain: {caller_node_name}"
+                )
+                self.generic_visit(node)
+                return
+
+            if not caller_type:
+                self.generic_visit(node)
+                return
+
+            method_func = getattr(caller_type, node.attr, None)
+            if not method_func:
+                self.generic_visit(node)
+                return
+
+            module = inspect.getmodule(caller_type)
+            if not module:
+                self.generic_visit(node)
+                return
+
+            source = inspect.getsource(module)
+            tree = ast.parse(source)
+            cls_ast = _find_in_module(
+                tree,
+                lambda n: isinstance(n, ast.ClassDef)
+                and n.name == caller_type.__name__,
+            )
+            if cls_ast:
+                casted_cls_ast = typing.cast(ast.ClassDef, cls_ast)
+                submethod = _find_method_node_in_cls(casted_cls_ast, node.attr)
+                if submethod:
+                    excs = _find_explicit_expection_recursively(
+                        method_func, submethod, self.should_search_module_pred
+                    )
+                    self.exceptions.extend(excs)
+
+        self.generic_visit(node)
+        return

richapi/exc_parser/openapi.py

@@ -0,0 +1,309 @@
+import ast
+import inspect
+import typing
+from functools import reduce
+from logging import getLogger
+from typing import Callable, Union
+
+import fastapi
+from fastapi import FastAPI
+from fastapi.dependencies.models import Dependant
+from fastapi.openapi.utils import get_openapi as _get_openapi
+from fastapi.routing import APIRoute
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from richapi.exc_parser.compiler import (
+    find_explicit_exceptions as _find_explicit_exceptions,
+)
+from richapi.exc_parser.protocol import (
+    BaseHTTPException,
+    HTTPExceptionSchema,
+    _generic_json_schema_builder,
+)
+from richapi.exceptions import BaseRichAPIException
+
+logger = getLogger(__name__)
+
+
+def load_openapi(
+    app: FastAPI,
+    openapi_json: dict,
+) -> Callable:
+    return lambda: openapi_json
+
+
+def enrich_openapi(
+    app: FastAPI,
+    target_module: Union[list[str], str, None] = None,
+    open_api_getter: Callable[[FastAPI], dict] = lambda app: _get_openapi(
+        title=app.title,
+        version=app.version,
+        description=app.description,
+        routes=app.routes,
+    ),
+) -> Callable:
+    if target_module is None:
+        target_module = _find_module_name_where_app_defined_in(app)
+        if target_module is None or target_module == "__main__":
+            raise BaseRichAPIException(
+                "Could not determine the module where the FastAPI instance was created.\n"
+                "Please provide the module name as a string or list of strings."
+            )
+
+    def _custom_openapi() -> dict:
+        if app.openapi_schema:  # pragma: no cover
+            return app.openapi_schema
+
+        app.openapi_schema = compile_openapi_from_fastapi(
+            app, target_module, open_api_getter
+        )
+        return app.openapi_schema
+
+    return _custom_openapi
+
+
+def compile_openapi_from_fastapi(
+    app: FastAPI,
+    target_module: Union[list[str], str],
+    open_api_getter: Callable[[FastAPI], dict] = lambda app: _get_openapi(
+        title=app.title,
+        version=app.version,
+        description=app.description,
+        routes=app.routes,
+    ),
+) -> dict:
+    openapi_schema = open_api_getter(app)
+    for route in app.routes:
+        if not isinstance(route, APIRoute):
+            continue
+
+        if route.include_in_schema:
+            exceptions = _extract_starlette_exceptions(route, target_module)
+
+            _fill_openapi_with_excpetions(openapi_schema, route, exceptions)
+
+    return openapi_schema
+
+
+def _find_module_name_where_app_defined_in(app: FastAPI) -> Union[str, None]:
+    frame = inspect.currentframe()
+    target_module = None
+    while frame:
+        for var_name, var_value in frame.f_globals.items():
+            if isinstance(var_value, FastAPI) and var_value is app:
+                target_module = frame.f_globals["__name__"]
+                break
+        if target_module:
+            break
+        frame = frame.f_back
+
+    return target_module
+
+
+def _resolve_status_and_detail_from_exc_type(
+    exc_type: type[Exception],
+    ast_raise: ast.Raise,
+) -> Union[tuple[int, Union[str, None]], None]:
+    if hasattr(exc_type, "status_code") and hasattr(exc_type, "detail"):
+        return (int(exc_type.status_code), exc_type.detail)  # type: ignore
+
+    ast_exc = ast_raise.exc
+    if not ast_exc:
+        return None
+
+    ast_kwargs = getattr(ast_exc, "keywords", None)
+    kwargs = {}
+    found_status_code: Union[int, None] = None
+    found_detail: Union[str, None] = None
+
+    if isinstance(ast_kwargs, list):
+        for kwarg in ast_kwargs:
+            if not hasattr(kwarg, "arg"):
+                continue
+
+            # that's the keyword argument in StarletteHTTPException
+            if kwarg.arg == "status_code":
+                status_code_value = kwarg.value
+
+                if isinstance(status_code_value, ast.Constant):
+                    found_status_code: Union[int, None] = int(status_code_value.value)
+
+                elif isinstance(status_code_value, ast.Attribute):
+                    # maybe used like: status.HTTP_404_NOT_FOUND
+                    left_hand_side = status_code_value.attr
+                    found_status_code = getattr(fastapi.status, left_hand_side, None)
+
+                elif isinstance(status_code_value, ast.Name):
+                    # maybe used like: HTTP_404_NOT_FOUND
+                    left_hand_side = status_code_value.id
+                    found_status_code = getattr(fastapi.status, left_hand_side, None)
+
+            elif kwarg.arg == "detail":
+                detail_value = kwarg.value
+                if isinstance(detail_value, ast.Constant):
+                    found_detail: Union[str, None] = detail_value.value
+
+            else:
+                if isinstance(kwarg.value, ast.Constant):
+                    kwargs[kwarg.arg] = kwarg.value.value
+
+    if found_detail and found_status_code:
+        return found_status_code, found_detail
+
+    ast_args = getattr(ast_exc, "args", None)
+    args = []
+
+    if isinstance(ast_args, list):
+        arg_values = [arg.value for arg in ast_args if isinstance(arg, ast.Constant)]
+
+        # we have some non-constant args and some constant args
+        if arg_values and len(arg_values) != len(ast_args):
+            status_arg = [arg for arg in arg_values if isinstance(arg, int)]
+            #  We can't construct the exception object anymore
+            if found_status_code:  # we have found status code in kwargs
+                return found_status_code, None
+            elif status_arg:  #  fall back to finding any integer value
+                return status_arg[0], None
+            return None  # give up
+
+        args.extend(arg_values)
+    else:
+        logger.debug(
+            f"Could not extract args from exception {exc_type}: {ast.dump(ast_exc)}"
+        )
+
+    try:
+        exc = exc_type(*args, **kwargs)
+        if hasattr(exc, "status_code") and hasattr(exc, "detail"):
+            return (int(exc.status_code), exc.detail)  # type: ignore
+
+        if found_status_code:
+            return found_status_code, None
+
+    except Exception as err:
+        logger.debug(
+            f"Could not construct exception {exc_type} with args: {args} and kwargs: {kwargs}",
+            exc_info=err,
+        )
+
+        if found_status_code:
+            return found_status_code, None
+
+    return None
+
+
+def _extract_json_schema(
+    ast_node: ast.Raise, exc: type[StarletteHTTPException]
+) -> Union[HTTPExceptionSchema, None]:
+    status_detail_pair = _resolve_status_and_detail_from_exc_type(exc, ast_node)
+    if status_detail_pair is None:
+        logger.debug(f"Could not resolve status code and detail for exception {exc}")
+        return None
+    status_code, detail = status_detail_pair
+    schema = _generic_json_schema_builder(exc, detail, status_code)
+    return schema
+
+
+def _fill_openapi_with_excpetions(
+    api_schema: dict,
+    route: APIRoute,
+    exceptions: list[tuple[type[StarletteHTTPException], ast.Raise]],
+) -> None:
+    for exc, ast_node in exceptions:
+        if hasattr(exc, "get_json_schema"):
+            casted_exc = typing.cast(type[BaseHTTPException], exc)
+            schema = casted_exc.get_json_schema()
+        else:
+            schema = _extract_json_schema(ast_node, exc)
+
+        if schema is None:
+            continue
+
+        str_status_code = str(schema.status_code)
+        component_schemas = api_schema.get("components", {}).get("schemas", {})
+        if schema.schema_name not in component_schemas:
+            if "components" not in api_schema:
+                api_schema["components"] = {"schemas": {}}
+            if "schemas" not in api_schema["components"]:
+                api_schema["components"]["schemas"] = {}
+
+            api_schema["components"]["schemas"][schema.schema_name] = (
+                schema.response_schema_json
+            )
+
+        path = route.path
+        methods = [method.lower() for method in getattr(route, "methods")]
+
+        for method in methods:
+            this_status_resp = api_schema["paths"][path][method]["responses"].get(
+                str_status_code, None
+            )
+
+            if this_status_resp is None:
+                api_schema["paths"][path][method]["responses"][str_status_code] = {
+                    "description": schema.schema_desc,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": f"#/components/schemas/{schema.schema_name}"
+                            }
+                        }
+                    },
+                }
+
+            else:
+                # HANDLE UNION
+                this_schema = this_status_resp["content"]["application/json"]["schema"]
+
+                if "anyOf" not in this_schema:
+                    this_status_resp["content"]["application/json"]["schema"] = {
+                        "anyOf": [
+                            this_schema,
+                            {"$ref": f"#/components/schemas/{schema.schema_name}"},
+                        ]
+                    }
+
+                else:
+                    this_schema["anyOf"].append(
+                        {"$ref": f"#/components/schemas/{schema.schema_name}"}
+                    )
+
+
+def build_dependency_tree(dependant: Dependant) -> list[Callable]:
+    """
+    Traverse the dependency tree and find all functions ('call' attribute)
+    from the dependencies that include 'func' in their name or signature.
+    """
+    dependencies_with_func: list[Callable] = []
+    if dependant.call:
+        dependencies_with_func.append(dependant.call)
+    for inner_dep in dependant.dependencies:
+        dependencies_with_func.extend(build_dependency_tree(inner_dep))
+    return dependencies_with_func
+
+
+T = typing.TypeVar("T")
+
+
+def flatten(to_be_flatten: list[list[T]]) -> list[T]:
+    return list(reduce(lambda x, y: x + y, to_be_flatten, []))
+
+
+def _extract_starlette_exceptions(
+    route: APIRoute, target_module: Union[list[str], str]
+) -> list[tuple[type[StarletteHTTPException], ast.Raise]]:
+    dependency_tree = build_dependency_tree(route.dependant)
+    exceptions = flatten(
+        [_find_explicit_exceptions(dep, target_module) for dep in dependency_tree]
+    )
+
+    starlette_http_exc_types = [
+        exc
+        for exc in exceptions
+        if exc[0] is not None and issubclass(exc[0], StarletteHTTPException)
+    ]
+    casted_exceptions = typing.cast(
+        list[tuple[type[StarletteHTTPException], ast.Raise]],
+        starlette_http_exc_types,
+    )
+    return casted_exceptions

richapi/exc_parser/protocol.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from fastapi import HTTPException
+from pydantic import BaseModel, create_model
+
+
+class HTTPExceptionSchema(BaseModel):
+    response_schema_json: dict[str, Any]
+    """Json schema representing the respone of the exception"""
+    schema_name: str
+    """Name of the schema"""
+    schema_desc: str
+    """Description of the schema"""
+    status_code: int
+    """Status code of the exception"""
+
+
+class BaseHTTPException(HTTPException):
+    status_code: int
+    detail: str
+
+    def __init__(self):
+        super().__init__(status_code=self.status_code, detail=self.detail)
+
+    @classmethod
+    def get_json_schema(cls) -> HTTPExceptionSchema:
+        value = _generic_json_schema_builder(cls)
+        assert (
+            value is not None
+        )  # should never happen because status code is always set
+        return value
+
+
+def _generic_json_schema_builder(
+    cls: type[Exception],
+    detail: str | None = None,
+    status_code: int | None = None,
+) -> HTTPExceptionSchema | None:
+    name = f"{cls.__name__}ErrorSchema"
+
+    if hasattr(cls, "detail") and cls.detail and detail is None:  # type: ignore
+        detail = cls.detail  # type: ignore
+
+    if hasattr(cls, "status_code") and cls.status_code and status_code is None:  # type: ignore
+        status_code = cls.status_code  # type: ignore
+
+    if status_code is None:
+        return None
+
+    if detail is not None:
+        detail_type = Literal[detail]  # type: ignore
+    else:
+        detail_type = str
+
+    schema = create_model(name, detail=(detail_type, ...))
+
+    return HTTPExceptionSchema(
+        response_schema_json=schema.model_json_schema(),
+        schema_name=name,
+        status_code=status_code,
+        schema_desc=detail or "No description provided",  # type: ignore
+    )

richapi/exceptions.py

@@ -0,0 +1,2 @@
+class BaseRichAPIException(Exception):
+    """Base class for all exceptions in richapi module"""

richapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,37 @@
+Metadata-Version: 2.3
+Name: richapi
+Version: 0.1.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-Dist: loguru>=0.7.2
+Requires-Dist: typer>=0.12.5
+Description-Content-Type: text/markdown
+
+### Installation
+
+To install the package, run the following command:
+
+```bash
+pip install richapi
+```
+
+## Help
+
+See [documentation](https://manimozaffar.github.io/richapi/latest/) for more details.
+
+### Use Cases
+
+RichAPI is designed to simplify FastAPI projects by automatically generating documented HTTP responses from HTTPException without extra effort! 🎉
+
+This package is planned to have more features for now that might be essential for any FastAPI project later.
+
+What would you see WITHOUT RichAPI:
+![Screenshot](docs/images/without-richapi.png)
+
+After compiling OpenAPI WITH RichAPI (extended with all possible exceptions coming from your router):
+![Screenshot](docs/images/with-richapi.png)

richapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+richapi/__init__.py,sha256=zCC0XGgbQxAlKKNWHwpZyO4pqgtLDsGbxm-JDHG0FlU,193
+richapi/__version__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+richapi/cli.py,sha256=d2DPwp5tavypSszPHYuAPOA2ktO1nxtOTnHqHDlK1KM,2536
+richapi/exceptions.py,sha256=DQU5gj8veUHhn7BxrhFH-3lQzIfuJcWqlJE2fKh-U60,97
+richapi/exc_parser/__init__.py,sha256=M88S8H5DBfYUt9odbUJH62gliiRwMS4TnN9O5AAGFS0,237
+richapi/exc_parser/compiler.py,sha256=e78HwSKTPHqpmtv8YVk0sTlr89BnmWvKCe3NAsrdN44,15924
+richapi/exc_parser/openapi.py,sha256=WLSdp-obrM3sshDaVk8JzWNQpxxbLCM1w5UA7zMSFfA,10540
+richapi/exc_parser/protocol.py,sha256=xXLSV9djwd4DtS4DN-iHKQB1QgeDIvr_nr6KwMe40ck,1829
+richapi-0.1.0.dist-info/METADATA,sha256=lBvINz74br9GPfafp5Cy3c361PyxT5vScMclOjb7QTw,1228
+richapi-0.1.0.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+richapi-0.1.0.dist-info/entry_points.txt,sha256=BjKovYW30iyw_HgNL4kWqNRtg6RDpVUnJ3WzZFO5aDA,44
+richapi-0.1.0.dist-info/RECORD,,

richapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

richapi-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+richapi = richapi.cli:app