richapi 0.3.0__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: richapi
-Version: 0.3.0
+Version: 0.3.1
 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

{richapi-0.3.0 → richapi-0.3.1}/docs/conventions.md

@@ -89,3 +89,29 @@ Keep it simple, keep the exception type next to raise keyword; without any dynam
 !!! info "Expected Behavior"
 
     Library **MIGHT skip** adding the exception to the OpenAPI schema depending on how complicated the exception raising is.
+
+## Always Provide Type Annotations For Class/Instance Attributes And Function Arguments
+
+To enable accurate type resolution during static analysis, always provide type annotations for your variables, function parameters, and return types. Without type annotations, it's nearly impossible for the library to infer types correctly, which may lead to false positives or negatives. That stands for class attributes and function arguments.
+
+Example:
+
+```Python hl_lines="6 12"
+class Foo:
+    def foo(self) -> None:
+        raise HTTPException(status_code=400, detail="This is not allowed")
+
+class Baz:
+    foo: Foo # this is very important to have type annotations for class/instance attributes
+
+    def __init__(self, foo: Foo):
+        self.foo = foo
+
+    def foo(self) -> None:
+        # if you don't type annotate, RichAPI doesn't have any idea about the type of self.fo
+        self.foo.foo()
+```
+
+!!! info "Expected Behavior"
+
+    Library **WILL skip** adding exceptions to the OpenAPI schema if it cannot resolve types due to missing annotations.

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

@@ -1,6 +1,6 @@
 [project]
 name = "richapi"
-version = "0.3.0"
+version = "0.3.1"
 description = "Find HTTPExceptions and turn them into documented responses!"
 readme = "README.md"
 requires-python = ">=3.9"

richapi-0.3.1/richapi/__version__.py

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

{richapi-0.3.0 → richapi-0.3.1}/richapi/exc_parser/compiler.py

@@ -4,9 +4,11 @@ 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
+from types import ModuleType
+from typing import Annotated, Callable, Generic, List, NewType, Optional, Tuple, Union
+
+import typing_extensions
 
 logger = logging.getLogger(__name__)
 
@@ -88,16 +90,15 @@ def get_func_name(func: Callable) -> str:
 
 
 def _find_all_class_exceptions(
-    cls: type,
+    cls: Union[type, Callable],
     to_filter_predicate: Callable[[str], bool],
     tree: Optional[ast.AST] = None,
 ):
     try:
         tree = tree or ast.parse(inspect.getsource(cls))
     except Exception as error:
-        logger.exception(
-            f"Failed to parse source code for {cls.__name__}.", exc_info=error
-        )
+        cls_name = cls.__name__ if hasattr(cls, "__name__") else cls.__str__()
+        logger.exception(f"Failed to parse source code for {cls_name}.", exc_info=error)
         return []
 
     result = _find_explicit_expection_recursively(
@@ -131,25 +132,24 @@ def _find_explicit_expection_recursively(
     tree: Optional[ast.AST] = None,
 ) -> list[tuple[Optional[type[Exception]], ast.Raise]]:
     if func_obj in ExceptionFinder.visited:
-        return []
+        return ExceptionFinder.visited[func_obj]
 
     module = inspect.getmodule(func_obj)
-    if module and is_stdlib(module.__name__):
-        return []
-
-    if module and to_filter_predicate(module.__name__) is False:
+    if module is None or _should_be_visited(module, to_filter_predicate) is False:
         return []
 
     if is_absolutely_callable_object(func_obj):
-        cls_module = inspect.getmodule(type(func_obj))
+        class_type: Union[type, Callable] = (
+            obj_type if (obj_type := type(func_obj)) is not type else func_obj
+        )
+
+        cls_module = inspect.getmodule(class_type)
         if cls_module and is_stdlib(cls_module.__name__):
             return []
         if cls_module and to_filter_predicate(cls_module.__name__) is False:
             return []
 
-        return _find_all_class_exceptions(type(func_obj), to_filter_predicate, tree)
-
-    ExceptionFinder.visited.add(func_obj)
+        return _find_all_class_exceptions(class_type, to_filter_predicate, tree)
 
     if tree is None:
         try:
@@ -178,6 +178,7 @@ def _find_explicit_expection_recursively(
             f"Failed to analyze function {get_func_name(func_obj)}.", exc_info=error
         )
 
+    ExceptionFinder.visited[func_obj] = finder.exceptions
     return finder.exceptions
 
 
@@ -227,12 +228,52 @@ def _resolve_full_attribute_path(node: ast.AST) -> Union[str, None]:
     return None
 
 
-def _resolve_function_from_call_node(
+def _retrieve_from_annotations(func: Callable, var_name: str) -> Optional[type]:
+    result = func.__annotations__.get(var_name, None)
+    if result is None:
+        return None
+
+    origin = typing.get_origin(result)
+    if origin is Annotated:
+        return result.__origin__
+    elif origin is not None and origin != Generic:
+        return origin
+    return result
+
+
+def _resolve_type_from_assigment(
+    resolved_value: Union[str, type, None],
+    assignments: dict[NodeIdentifier, str],
+    func: Callable,
+):
+    if resolved_value is None:
+        return None
+
+    # because assigment are stored as string
+    # ! A string type could be also called like str("Foo").lower() so we fallback to parent_attr in case it remains as string
+
+    if isinstance(resolved_value, str):
+        resolved_value = func.__globals__.get(resolved_value, resolved_value)
+
+    if isinstance(resolved_value, str):
+        resolved_value = assignments.get(NodeIdentifier(resolved_value), resolved_value)
+
+    if isinstance(resolved_value, str):
+        resolved_value = (
+            _retrieve_from_annotations(func, resolved_value) or resolved_value
+        )
+
+    if isinstance(resolved_value, str):  # last fallback
+        resolved_value = _exctact_type(resolved_value, func.__globals__)
+
+    return resolved_value
+
+
+def _resolve_functions_from_call_node(
     call_node: ast.Call,
-    func_globals: dict,
     func: Callable,
     assignments: dict[NodeIdentifier, str],
-):
+) -> list[type]:
     """
     Attempt to resolve the function object from a call node.
     Handles both simple function calls and method calls.
@@ -241,7 +282,7 @@ def _resolve_function_from_call_node(
 
     if isinstance(node, ast.Name):
         # Simple function call: func()
-        value = func_globals.get(node.id, None)
+        value = func.__globals__.get(node.id, None)
 
         if value is None:
             value = getattr(builtins, node.id, None)
@@ -249,7 +290,9 @@ def _resolve_function_from_call_node(
         if value is None:
             logger.debug(f"Function '{node.id}' not found in {func.__name__}")
 
-        return value
+        if value is not None:
+            return [value]
+        return []
 
     elif isinstance(node, ast.Attribute):
         attr_chain = _resolve_full_attribute_path(node)
@@ -257,46 +300,89 @@ def _resolve_function_from_call_node(
             logger.debug(
                 f"Failed to get full attribute name: {ast.dump(node)} in {func.__name__}"
             )
-            return None
+            return []
 
         try:
             parts = attr_chain.split(".")
             parent_part = parts[0]
 
-            parent_attr = func_globals.get(parent_part, None)
+            parent_attr = func.__globals__.get(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 in func.__annotations__:
-                    return func.__annotations__[parent_part]
+                    result = _retrieve_from_annotations(func, parent_part)
+                    return [] if result is None else [result]
 
                 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
+                # use case where you're calling self.foo.do_something(), where self.foo is a class attribute that is a class itself
+                if parent_part == "self" or parent_part == "cls":
+                    property_name = parts[1]
+                    # ['class_name', 'method_name']
+                    qual_names = func.__qualname__.split(".")
+                    # ['class_name']
+                    func_name_index = qual_names.index(func.__name__)
+                    # 'class_name'
+                    cls_name = qual_names[func_name_index - 1]
+                    # class_name (type)
+                    cls: Union[Callable, None] = func.__globals__.get(cls_name, None)
+
+                    if cls is None:
+                        logger.debug(
+                            f"Failed to resolve parent class {cls} for parts {attr_chain}. Chain: {ast.dump(node)} for func {func.__name__}"
+                        )
+                        return []
+                    attr_class = _retrieve_from_annotations(cls, property_name)
+                    if attr_class is None:  # part of convention
+                        return []
+
+                    results: list[type] = []
+                    try:
+                        obj = getattr(attr_class, "__init__", None)
+                        if obj is not None:
+                            results.append(obj)
+                    except Exception:
+                        pass
+
+                    for attr in parts[2:]:
+                        try:
+                            obj = getattr(attr_class, attr, None)
+
+                            if obj is not None:
+                                results.append(obj)
+                        except Exception:
+                            break
+
+                    return results
 
                 logger.debug(
                     f"Failed to resolve parent attribute {parent_part} for parts {attr_chain}. Chain: {ast.dump(node)} for func {func.__name__}"
                 )
-                return None
+                return []
 
+            parent_attr = _resolve_type_from_assigment(parent_attr, assignments, func)
+            results: list[type] = []
             for attr in parts[1:]:
                 try:
                     obj = getattr(parent_attr, attr, None)
+                    if obj is not None:
+                        results.append(obj)
+
                 except Exception:
                     break
 
-                return obj
+            return results
 
         except Exception:
             logger.exception(f"Failed to resolve attribute chain: {attr_chain}")
-            return None
+            return []
+
+    return []
 
 
 def _extract_node_name(
@@ -349,7 +435,19 @@ def _exctact_type(var_tyep: str, func_globals: dict) -> Optional[type]:
         logger.exception(f"Failed to resolve variable type: {var_tyep}")
 
 
-@lru_cache
+def _should_be_visited(
+    module: ModuleType,
+    should_search_module_pred: Callable[[str], bool],
+):
+    if (
+        is_stdlib(module.__name__)
+        or should_search_module_pred(module.__name__) is False
+    ):
+        return False
+
+    return True
+
+
 def is_stdlib(module_name: str) -> bool:
     """Check if a given module is part of the Python standard library."""
     try:
@@ -364,18 +462,29 @@ def is_stdlib(module_name: str) -> bool:
 
 
 class ExceptionFinder(ast.NodeVisitor):
-    visited: set[Callable] = set()
+    visited: dict[Callable, list[tuple[Optional[type[Exception]], ast.Raise]]] = {}
+    # cached_assignments: dict[Callable, dict[NodeIdentifier, str]] = {}
 
     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.cached_assignments[func] = self.assignments
         self.func = func
-        self.func_globals = func.__globals__
         self.should_search_module_pred = should_search_module_pred
         logger.info(f"Analyzing function {func.__name__}")
 
+    @classmethod
+    def clear_cache(cls):
+        cls.visited.clear()
+        # cls.cached_assignments.clear()
+
+    def _should_be_visited(
+        self, module: ModuleType
+    ) -> typing_extensions.TypeGuard[ModuleType]:
+        return _should_be_visited(module, self.should_search_module_pred)
+
     def visit_Assign(self, node):
         """
         Track assignments to variables that are exceptions or exception instances.
@@ -401,10 +510,11 @@ class ExceptionFinder(ast.NodeVisitor):
 
         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
+                var_name = get_node_identifier(target)
+                var_result = _extract_node_name(value, self.assignments)
+
+                if var_result is not None:
+                    self.assignments[var_name] = var_result
 
                 else:
                     # no need to log here. it would be very spammy
@@ -457,7 +567,7 @@ class ExceptionFinder(ast.NodeVisitor):
             logger.debug(f"Failed to get exception name: {ast.dump(node)}")
             return
 
-        exc_type = _exctact_type(exc_variable_name, self.func_globals)
+        exc_type = _exctact_type(exc_variable_name, self.func.__globals__)
 
         if exc_type:
             self.exceptions.append((exc_type, node))
@@ -469,50 +579,47 @@ class ExceptionFinder(ast.NodeVisitor):
         """
         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)
-            try:
-                tree = ast.parse(source)
-            except BaseException as error:
-                logger.exception(
-                    f"Failed to parse source code for {func_obj.__name__}.",
-                    exc_info=error,
+        func_objs = _resolve_functions_from_call_node(node, self.func, self.assignments)
+        for func_obj in func_objs:
+            if inspect.isfunction(func_obj):
+                module = inspect.getmodule(func_obj)
+                if module is None or self._should_be_visited(module) is False:
+                    continue
+
+                source = inspect.getsource(module)
+                try:
+                    tree = ast.parse(source)
+                except BaseException as error:
+                    logger.exception(
+                        f"Failed to parse source code for {func_obj.__name__}.",
+                        exc_info=error,
+                    )
+                    self.generic_visit(node)
+                    return
+
+                founded_func_ast = _find_in_module(
+                    tree,
+                    lambda n: (
+                        isinstance(n, ast.AsyncFunctionDef)
+                        or isinstance(n, ast.FunctionDef)
+                    )
+                    and n.name == func_obj.__name__,
                 )
-                self.generic_visit(node)
-                return
+                if founded_func_ast:
+                    excs = _find_explicit_expection_recursively(
+                        func_obj, self.should_search_module_pred, founded_func_ast
+                    )
+                    self.exceptions.extend(excs)
+                else:
+                    logger.debug(
+                        f"Failed to find function {func_obj.__name__} in module {module.__name__}"
+                    )
 
-            founded_func_ast = _find_in_module(
-                tree,
-                lambda n: (
-                    isinstance(n, ast.AsyncFunctionDef)
-                    or isinstance(n, ast.FunctionDef)
-                )
-                and n.name == func_obj.__name__,
-            )
-            if founded_func_ast:
-                excs = _find_explicit_expection_recursively(
-                    func_obj, self.should_search_module_pred, founded_func_ast
-                )
-                self.exceptions.extend(excs)
-            else:
-                logger.debug(
-                    f"Failed to find function {func_obj.__name__} in module {module.__name__}"
+            elif inspect.isclass(func_obj):
+                _excs = _find_explicit_expection_recursively(
+                    func_obj, self.should_search_module_pred
                 )
+                self.exceptions.extend(_excs)
 
         self.generic_visit(node)
         return
@@ -527,7 +634,7 @@ class ExceptionFinder(ast.NodeVisitor):
                 return
 
             try:
-                caller_type = _exctact_type(caller_node_name, self.func_globals)
+                caller_type = _exctact_type(caller_node_name, self.func.__globals__)
             except Exception:
                 logger.critical(
                     f"Failed to resolve attribute chain: {caller_node_name}"
@@ -545,7 +652,7 @@ class ExceptionFinder(ast.NodeVisitor):
                 return
 
             module = inspect.getmodule(caller_type)
-            if not module:
+            if module is None or self._should_be_visited(module) is False:
                 self.generic_visit(node)
                 return
 

{richapi-0.3.0 → richapi-0.3.1}/richapi/exc_parser/openapi.py

@@ -91,7 +91,7 @@ def compile_openapi_from_fastapi(
 
             _fill_openapi_with_excpetions(openapi_schema, route, exceptions)
 
-    ExceptionFinder.visited.clear()
+    ExceptionFinder.clear_cache()
 
     return openapi_schema
 

richapi-0.3.1/tests/app/foo1.py

@@ -0,0 +1,10 @@
+from richapi.exc_parser.protocol import BaseHTTPException
+
+
+class HTTP500Error(BaseHTTPException):
+    status_code = 500
+    detail = "Internal Server Error"
+
+
+def raise_exc():
+    raise HTTP500Error

richapi-0.3.1/tests/test_builder_pattern.py

@@ -0,0 +1,68 @@
+import fastapi
+import fastapi.security
+from pydantic.dataclasses import dataclass
+
+from richapi.exc_parser.handler import add_exc_handler
+from richapi.exc_parser.openapi import compile_openapi_from_fastapi, enrich_openapi
+from richapi.exc_parser.protocol import RichHTTPException
+
+app = fastapi.FastAPI()
+app.openapi = enrich_openapi(app)
+add_exc_handler(app)
+
+
+@dataclass
+class Exception1(RichHTTPException):
+    status_code = 409
+
+
+@dataclass
+class Exception2(RichHTTPException):
+    status_code = 408
+
+
+@dataclass
+class Exception3(RichHTTPException):
+    status_code = 407
+
+
+def foo1():
+    raise Exception1()
+
+
+def foo2():
+    raise Exception2()
+
+
+def foo3():
+    raise Exception3()
+
+
+class PaymentService:
+    def foo(self):
+        foo1()
+        return self
+
+    def create(self):
+        foo2()
+        return self
+
+    def update(self):
+        foo3()
+        return self
+
+
+@app.post("/payment")
+async def make_payment():
+    PaymentService().foo().create().update()
+
+
+def test_class_is_detected():
+    openapi_json = compile_openapi_from_fastapi(
+        app, target_module="tests.test_builder_pattern"
+    )
+    home_responses = openapi_json["paths"]["/payment"]["post"]["responses"]
+    print(home_responses)
+    assert "408" in home_responses
+    assert "407" in home_responses
+    assert "409" in home_responses

richapi-0.3.1/tests/test_class.py

@@ -0,0 +1,72 @@
+import fastapi
+import fastapi.security
+from pydantic.dataclasses import dataclass
+
+from richapi.exc_parser.handler import add_exc_handler
+from richapi.exc_parser.openapi import compile_openapi_from_fastapi, enrich_openapi
+from richapi.exc_parser.protocol import RichHTTPException
+
+app = fastapi.FastAPI()
+app.openapi = enrich_openapi(app)
+add_exc_handler(app)
+
+
+@dataclass
+class Exception1(RichHTTPException):
+    status_code = 409
+
+
+@dataclass
+class Exception2(RichHTTPException):
+    status_code = 408
+
+
+@dataclass
+class Exception3(RichHTTPException):
+    status_code = 407
+
+
+def foo1():
+    raise Exception1()
+
+
+def foo2():
+    raise Exception2()
+
+
+def foo3():
+    raise Exception3()
+
+
+class PaymentService:
+    def __init__(self):
+        foo1()
+
+    def create(self):
+        foo2()
+
+    def update(self):
+        foo3()
+
+
+def make_payment_dep():
+    obj = PaymentService()
+    return obj
+
+
+@app.post("/payment")
+async def make_payment(
+    obj2: PaymentService = fastapi.Depends(make_payment_dep),
+):
+    obj = PaymentService()
+    obj.create()
+    obj2.update()
+
+
+def test_class_is_detected():
+    openapi_json = compile_openapi_from_fastapi(app, target_module="tests.test_class")
+    home_responses = openapi_json["paths"]["/payment"]["post"]["responses"]
+    print(home_responses)
+    assert "408" in home_responses
+    assert "407" in home_responses
+    assert "409" in home_responses

richapi-0.3.1/tests/test_compiler.py

@@ -0,0 +1,12 @@
+from typing import Annotated
+
+from richapi.exc_parser.compiler import _retrieve_from_annotations
+
+
+def foo(value: Annotated[int, Annotated[str, str]]): ...
+
+
+def test_get_from_annotated():
+    result = _retrieve_from_annotations(foo, "value")
+    print(type(result))
+    assert result is int

richapi-0.3.1/tests/test_import_from_other_module.py

@@ -0,0 +1,20 @@
+import fastapi
+import fastapi.security
+
+from richapi.exc_parser.openapi import compile_openapi_from_fastapi, enrich_openapi
+from tests.app import foo1 as FooService
+
+app = fastapi.FastAPI()
+app.openapi = enrich_openapi(app)
+
+
+@app.post("/payment")
+async def make_payment():
+    FooService.raise_exc()
+
+
+def test_class_is_detected():
+    openapi_json = compile_openapi_from_fastapi(app, target_module="tests")
+    home_responses = openapi_json["paths"]["/payment"]["post"]["responses"]
+    print(home_responses)
+    assert "500" in home_responses

richapi-0.3.1/tests/test_instance_attr_call.py

@@ -0,0 +1,82 @@
+import logging
+
+import fastapi
+import fastapi.security
+from pydantic.dataclasses import dataclass
+
+from richapi.exc_parser.openapi import compile_openapi_from_fastapi, enrich_openapi
+from richapi.exc_parser.protocol import RichHTTPException
+
+logging.getLogger().addHandler(logging.StreamHandler())
+
+app = fastapi.FastAPI()
+app.openapi = enrich_openapi(app, target_module="tests.test_instance_attr_call")
+
+
+@dataclass
+class Exception1(RichHTTPException):
+    status_code = 409
+
+
+@dataclass
+class Exception2(RichHTTPException):
+    status_code = 408
+
+
+@dataclass
+class Exception3(RichHTTPException):
+    status_code = 407
+
+
+def foo1():
+    raise Exception1()
+
+
+def foo2():
+    raise Exception2()
+
+
+def foo3():
+    raise Exception3()
+
+
+class PaymentService:
+    def __init__(self):
+        foo1()
+
+    def create_inner(self):
+        foo2()
+
+    def update_inner(self):
+        foo3()
+
+
+class PaymentOrchestrator:
+    service: PaymentService
+
+    def __init__(self, payment_service: PaymentService):
+        self.service = payment_service
+
+    def create_outer(self):
+        self.service.create_inner()
+        self.update_outer()
+
+    def update_outer(self):
+        self.service.update_inner()
+
+
+@app.post("/payment")
+async def make_payment():
+    obj = PaymentOrchestrator(payment_service=PaymentService())
+    obj.create_outer()
+
+
+def test_class_is_detected():
+    openapi_json = compile_openapi_from_fastapi(
+        app, target_module="tests.test_instance_attr_call"
+    )
+    home_responses = openapi_json["paths"]["/payment"]["post"]["responses"]
+    print(home_responses)
+    assert "408" in home_responses
+    assert "407" in home_responses
+    assert "409" in home_responses

richapi-0.3.0/richapi/__version__.py

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