richapi 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: richapi
-Version: 0.2.0
+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.0 → 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.0 → 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.0 → 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.0 → richapi-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "richapi"
-version = "0.2.0"
+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.0 → richapi-0.3.0}/richapi/exc_parser/compiler.py

@@ -114,15 +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)
+        and (not inspect.isfunction(obj))
+        and (not inspect.ismethod(obj))
     )
 
 
@@ -142,6 +141,12 @@ def _find_explicit_expection_recursively(
         return []
 
     if is_absolutely_callable_object(func_obj):
+        cls_module = inspect.getmodule(type(func_obj))
+        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)

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.0 → 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,
 )
@@ -44,12 +47,15 @@ def enrich_openapi(
 ) -> 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."
             )
 
+        target_module = target_module.split(".")[0]  # get the top-level module
+
     def _custom_openapi() -> dict:
         if app.openapi_schema:  # pragma: no cover
             return app.openapi_schema
@@ -85,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.0 → 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):
@@ -33,15 +34,47 @@ class BaseHTTPException(HTTPException):
         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:
-    if " " in string:  # with space
+    final_str = string
+    if " " in final_str:  # with space
         components = string.split(" ")
-        return components[0] + "".join(x.title() for x in components[1:])
-    elif "_" in string:  # snake case
+        final_str = components[0] + "".join(x.title() for x in components[1:])
+
+    if "_" in final_str:  # snake case
         components = string.split("_")
-        return components[0] + "".join(x.title() for x in components[1:])
-    else:
-        return string  # not known
+        final_str = components[0] + "".join(x.title() for x in components[1:])
+
+    if "-" in final_str:  # kebab case
+        components = string.split("-")
+        final_str = components[0] + "".join(x.title() for x in components[1:])
+
+    return final_str
 
 
 def _generic_json_schema_builder(

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.0/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.0/richapi/__version__.py

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