richapi 0.2.1__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: richapi
-Version: 0.2.1
+Version: 0.3.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

{richapi-0.2.1 → richapi-0.3.0}/docs/advance.md

@@ -4,9 +4,6 @@ This is guideline for how to use the library in more advanced ways.
 
 ### Customization of the OpenAPI schema
 
-Sometimes, your exceptions is more than 'details'.
-In that case, you can very explicitly define the exception JSON schema inside the exception class. You may even use Pydantic to define the schema dynamically so you don't need to write the schema manually.
-
 All you need to do, is to return type HTTPExceptionSchema correctly on the method `get_json_schema` of your exception class which you inherited from `BaseHTTPException`.
 
 Imagine you are writing an exception that is returning a user balance and a time to retry again a failed bank transaction, you can define the schema like this:
@@ -33,7 +30,7 @@ class YourException(BaseHTTPException):
 
 ```
 
-Remember that the responsbility of raising and returning the correct data on FastAPI is not library responsibility, but the responsibility of the developer. The library is only responsible for generating the OpenAPI schema by looking at the functions and classes that are raising exceptions.
+If your intention is to have a custom response schema, then recommended way is to use [custom exception feature](index.md#customization-of-exception).
 
 ### Finding exceptions in other modules
 

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

@@ -6,7 +6,7 @@ Since the library is a mini compiler using Abstract Syntax Tree and functions gl
 
 Keep in mind that if you don't follow these conventions, there would be alot false positive and false negative cases, and the library may not be able to extract the exceptions and their responses correctly.
 
-## Inherit from `richapi.BaseHTTPException`
+## Inherit from `richapi.BaseHTTPException` or `richapi.RichHTTPException`
 
 Exceptions are better to be very concrete, without having any dynamic data in them.
 So that using `raise Class` is enough to raise them.

{richapi-0.2.1 → richapi-0.3.0}/docs/index.md

@@ -46,6 +46,57 @@ with open("openapi.json") as open_api_json:
 
     I personally recommend the second way, because it is better to have it compiled and saved to file, because there are static analysis running on the OpanAPI generator and your source code which isn't very ideal to be running in production.
 
+### Customization of Exception
+
+Sometimes, your exceptions is more than 'details'. You may want to put some extra information for the client to understand and parse the error better. In that case, please follow these steps:
+
+1. Add the exception handler from richapi to your FastAPI app.
+2. Inhert from `richapi.RichHTTPException`, and make it a dataclass.
+3. To override status, simply set the `status_code` attribute on the class without type annotation.
+4. Raise that exception somewhere in your code and you'll see the schema on swagger!
+
+Example:
+
+```python
+import fastapi
+import fastapi.security
+from pydantic import BaseModel
+from pydantic.dataclasses import dataclass
+
+from richapi.exc_parser.handler import add_exc_handler
+from richapi.exc_parser.openapi import enrich_openapi
+from richapi.exc_parser.protocol import RichHTTPException
+
+app = fastapi.FastAPI()
+app.openapi = enrich_openapi(app)
+add_exc_handler(app)
+
+
+@dataclass
+class NotEnoughBalance(RichHTTPException):
+    """Custom exception for user balance"""
+
+    user_id: int
+    balance: float
+    status_code = 403
+
+
+class SuccessResponse(BaseModel):
+    balance: float
+
+
+@app.post("/payment")
+async def make_payment() -> SuccessResponse:
+    raise NotEnoughBalance(user_id=1, balance=0.5)
+```
+
+Final Result:
+![Screenshot](./images/custom-exception.png)
+
+### Conventions (VERY IMPORTANT)
+
+There are some conventions about how to raise exceptions and etc. You may read the [conventions](conventions.md) to know more about them. The way library works is that it is a mini compiler using Abstract Syntax Tree and functions global to extract exceptions and their responses, and then it generates the OpenAPI schema from them. So there are limitations to what it can do, and you may need to follow the conventions to get the best out of it. Anything that is not following the conventions MAY be ignored by the compiler, and there is no plan to support them in the future, because it is not possible to support all the ways you can raise exceptions in Python... To give you an example, you may download a source code from internet and then use 'eval' function to run it dynamically, and there is no way to know what exceptions you may raise in that code, so it is impossible to support all the ways you can raise exceptions in Python.
+
 ### Example
 
 Imagine this application;
@@ -105,7 +156,3 @@ What would you see WITHOUT RichAPI:
 
 After compiling OpenAPI WITH RichAPI (extended with all possible exceptions coming from your router):
 ![Screenshot](./images/with-richapi.png)
-
-### Conventions (VERY IMPORTANT)
-
-There are some conventions about how to raise exceptions and etc. You may read the [conventions](conventions.md) to know more about them. The way library works is that it is a mini compiler using Abstract Syntax Tree and functions global to extract exceptions and their responses, and then it generates the OpenAPI schema from them. So there are limitations to what it can do, and you may need to follow the conventions to get the best out of it. Anything that is not following the conventions MAY be ignored by the compiler, and there is no plan to support them in the future, because it is not possible to support all the ways you can raise exceptions in Python... To give you an example, you may download a source code from internet and then use 'eval' function to run it dynamically, and there is no way to know what exceptions you may raise in that code, so it is impossible to support all the ways you can raise exceptions in Python.

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

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

richapi-0.3.0/richapi/__init__.py

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

richapi-0.3.0/richapi/__version__.py

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

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

@@ -95,10 +95,14 @@ def _find_all_class_exceptions(
     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)
+        logger.exception(
+            f"Failed to parse source code for {cls.__name__}.", exc_info=error
+        )
         return []
 
-    result = _find_explicit_expection_recursively(cls.__init__, to_filter_predicate, tree)
+    result = _find_explicit_expection_recursively(
+        cls.__init__, to_filter_predicate, tree
+    )
     if hasattr(cls, "__call__"):
         # Not sure if __call__ was called or init, so check for both
 
@@ -110,13 +114,14 @@ def _find_all_class_exceptions(
             )
         )
 
-    ExceptionFinder.visited = set()  # clean up memory
     return result
 
 
 def is_absolutely_callable_object(obj: Callable) -> bool:
     return (
-        inspect.isclass(type(obj)) and (not inspect.isfunction(obj)) and (not inspect.ismethod(obj))
+        inspect.isclass(type(obj))
+        and (not inspect.isfunction(obj))
+        and (not inspect.ismethod(obj))
     )
 
 
@@ -169,7 +174,9 @@ def _find_explicit_expection_recursively(
     try:
         finder.visit(tree)
     except Exception as error:
-        logger.exception(f"Failed to analyze function {get_func_name(func_obj)}.", exc_info=error)
+        logger.exception(
+            f"Failed to analyze function {get_func_name(func_obj)}.", exc_info=error
+        )
 
     return finder.exceptions
 
@@ -247,7 +254,9 @@ def _resolve_function_from_call_node(
     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__}")
+            logger.debug(
+                f"Failed to get full attribute name: {ast.dump(node)} in {func.__name__}"
+            )
             return None
 
         try:
@@ -267,7 +276,9 @@ def _resolve_function_from_call_node(
                 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
+                if (
+                    parent_part == "self"
+                ):  # don't need to log -> we already know this is class
                     return None
 
                 logger.debug(
@@ -295,7 +306,9 @@ def _extract_node_name(
     Extract the exception name a node recursively.
     """
     if isinstance(node, ast.Call):
-        return _extract_node_name(typing.cast(SupportedAstNodes, node.func), assignments)
+        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)
@@ -303,7 +316,9 @@ def _extract_node_name(
         return _resolve_full_attribute_path(node)
 
     elif isinstance(node, ast.Await):
-        return _extract_node_name(typing.cast(SupportedAstNodes, node.value), assignments)
+        return _extract_node_name(
+            typing.cast(SupportedAstNodes, node.value), assignments
+        )
 
     elif isinstance(
         node,
@@ -351,7 +366,9 @@ def is_stdlib(module_name: str) -> bool:
 class ExceptionFinder(ast.NodeVisitor):
     visited: set[Callable] = set()
 
-    def __init__(self, func: Callable, should_search_module_pred: Callable[[str], bool]):
+    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
@@ -481,7 +498,10 @@ class ExceptionFinder(ast.NodeVisitor):
 
             founded_func_ast = _find_in_module(
                 tree,
-                lambda n: (isinstance(n, ast.AsyncFunctionDef) or isinstance(n, ast.FunctionDef))
+                lambda n: (
+                    isinstance(n, ast.AsyncFunctionDef)
+                    or isinstance(n, ast.FunctionDef)
+                )
                 and n.name == func_obj.__name__,
             )
             if founded_func_ast:
@@ -509,7 +529,9 @@ class ExceptionFinder(ast.NodeVisitor):
             try:
                 caller_type = _exctact_type(caller_node_name, self.func_globals)
             except Exception:
-                logger.critical(f"Failed to resolve attribute chain: {caller_node_name}")
+                logger.critical(
+                    f"Failed to resolve attribute chain: {caller_node_name}"
+                )
                 self.generic_visit(node)
                 return
 
@@ -540,7 +562,8 @@ class ExceptionFinder(ast.NodeVisitor):
 
             cls_ast = _find_in_module(
                 tree,
-                lambda n: isinstance(n, ast.ClassDef) and n.name == caller_type.__name__,
+                lambda n: isinstance(n, ast.ClassDef)
+                and n.name == caller_type.__name__,
             )
             if cls_ast:
                 casted_cls_ast = typing.cast(ast.ClassDef, cls_ast)

richapi-0.3.0/richapi/exc_parser/handler.py

@@ -0,0 +1,22 @@
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+from pydantic import TypeAdapter
+from starlette.requests import Request
+from starlette.responses import Response
+
+from richapi.exc_parser.protocol import RichHTTPException
+
+
+async def _handle_rich_http_exception(request: Request, exc: Exception) -> Response:
+    assert isinstance(exc, RichHTTPException)
+
+    adapter = TypeAdapter(exc.__class__)
+    if exc._validate_arg_types:
+        adapter.validate_python(exc)
+
+    json_response = adapter.dump_python(exc)
+    return JSONResponse(content=json_response, status_code=exc.status_code)
+
+
+def add_exc_handler(app: FastAPI):
+    app.add_exception_handler(RichHTTPException, handler=_handle_rich_http_exception)

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

@@ -12,6 +12,9 @@ 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 (
+    ExceptionFinder,
+)
 from richapi.exc_parser.compiler import (
     find_explicit_exceptions as _find_explicit_exceptions,
 )
@@ -88,6 +91,8 @@ def compile_openapi_from_fastapi(
 
             _fill_openapi_with_excpetions(openapi_schema, route, exceptions)
 
+    ExceptionFinder.visited.clear()
+
     return openapi_schema
 
 

{richapi-0.2.1 → richapi-0.3.0}/richapi/exc_parser/protocol.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
-from typing import Any, Literal
+from typing import Any, ClassVar, Literal
 
 from fastapi import HTTPException
-from pydantic import BaseModel, create_model
+from pydantic import BaseModel, TypeAdapter, create_model
+from pydantic.dataclasses import dataclass
 
 
 class HTTPExceptionSchema(BaseModel):
@@ -27,10 +28,38 @@ class BaseHTTPException(HTTPException):
     @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
+        assert (
+            value is not None
+        )  # should never happen because status code is always set
         return value
 
 
+@dataclass
+class RichHTTPException(HTTPException):
+    status_code: ClassVar[int] = 422
+    """HTTP Status code to raise"""
+
+    _validate_arg_types: ClassVar[bool] = True
+    """Whether to run validation on arguements"""
+
+    @classmethod
+    def get_json_schema(cls) -> HTTPExceptionSchema:
+        adapter = TypeAdapter(cls)
+        schema = adapter.json_schema()
+        schema.pop("status_code", None)
+
+        schema_desc = cls.__doc__
+        if schema_desc == cls.__name__ + "()" or schema_desc is None:
+            schema_desc = "No description provided"
+
+        return HTTPExceptionSchema(
+            response_schema_json=schema,
+            schema_name=f"{cls.__name__}Schema",
+            status_code=cls.status_code,
+            schema_desc=schema_desc,
+        )
+
+
 def try_to_camel_case(string: str) -> str:
     final_str = string
     if " " in final_str:  # with space

richapi-0.3.0/tests/test_custom_exc.py

@@ -0,0 +1,52 @@
+import fastapi
+import fastapi.security
+import pytest
+from httpx import ASGITransport, AsyncClient
+from pydantic import BaseModel
+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 NotEnoughBalance(RichHTTPException):
+    """Custom exception for user balance"""
+
+    user_id: int
+    balance: float
+    status_code = 409
+
+
+class SuccessResponse(BaseModel):
+    balance: float
+
+
+@app.post("/payment")
+async def make_payment() -> SuccessResponse:
+    raise NotEnoughBalance(user_id=1, balance=0.5)
+
+
+def test_custom_exc_detected():
+    openapi_json = compile_openapi_from_fastapi(
+        app, target_module="tests.test_custom_exc"
+    )
+    home_responses = openapi_json["paths"]["/payment"]["post"]["responses"]
+    assert "409" in home_responses
+
+
+@pytest.mark.asyncio
+async def test_make_payment():
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as ac:
+        response = await ac.post("/payment")
+
+    assert response.status_code == 409
+    expected_response = {"user_id": 1, "balance": 0.5}
+    assert response.json() == expected_response

richapi-0.2.1/richapi/__init__.py

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

richapi-0.2.1/richapi/__version__.py

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