jder-fastapi 0.1.0.dev1__tar.gz

jder_fastapi-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: jder-fastapi
+Version: 0.1.0.dev1
+Summary: A response builder for FastAPI
+Keywords: jder,json,response,fastapi,python
+Author: Alpheus
+Author-email: Alpheus <contact@alphe.us>
+License-Expression: MIT
+Classifier: Topic :: File Formats
+Classifier: Topic :: File Formats :: JSON
+Classifier: Topic :: File Formats :: JSON :: JSON Schema
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Dist: fastapi>=0.116.0,<0.117.0
+Requires-Python: >=3.13
+Project-URL: Changelog, https://github.com/jder-std/fastapi/blob/main/package/CHANGELOG.md
+Project-URL: Documentation, https://github.com/jder-std/fastapi/blob/main/docs/README.md
+Project-URL: Homepage, https://github.com/jder-std/fastapi
+Project-URL: Issues, https://github.com/jder-std/fastapi/issues
+Project-URL: Repository, https://github.com/jder-std/fastapi
+Description-Content-Type: text/markdown
+
+# JDER FastAPI
+
+A response builder for FastAPI.
+
+This package includes different response builders based on the JSON response structure specified in [JSON Data Errors Response (JDER)](https://github.com/jder-std/spec). With the builders, various kinds of responses can be created easily instead of sending plain text responses.
+
+## Quick Start
+
+To create a JSON response, use the following code:
+
+```python
+from fastapi import FastAPI
+from fastapi.responses import Response
+from jder_fastapi.responses.json import createJsonResponse
+
+app: FastAPI = FastAPI()
+
+@app.get("/")
+async def route() -> Response:
+    return createJsonResponse()
+```
+
+And the response will be shown as below:
+
+```json
+{
+    "success": true
+}
+```
+
+## License
+
+This project is licensed under the terms of the MIT license.

jder_fastapi-0.1.0.dev1/README.md

@@ -0,0 +1,33 @@
+# JDER FastAPI
+
+A response builder for FastAPI.
+
+This package includes different response builders based on the JSON response structure specified in [JSON Data Errors Response (JDER)](https://github.com/jder-std/spec). With the builders, various kinds of responses can be created easily instead of sending plain text responses.
+
+## Quick Start
+
+To create a JSON response, use the following code:
+
+```python
+from fastapi import FastAPI
+from fastapi.responses import Response
+from jder_fastapi.responses.json import createJsonResponse
+
+app: FastAPI = FastAPI()
+
+@app.get("/")
+async def route() -> Response:
+    return createJsonResponse()
+```
+
+And the response will be shown as below:
+
+```json
+{
+    "success": true
+}
+```
+
+## License
+
+This project is licensed under the terms of the MIT license.

jder_fastapi-0.1.0.dev1/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+[project]
+name = "jder-fastapi"
+version = "0.1.0.dev1"
+dependencies = [
+    "fastapi>=0.116.0,<0.117.0",
+]
+requires-python = ">=3.13"
+authors = [
+    { name = "Alpheus", email = "contact@alphe.us" }
+]
+description = "A response builder for FastAPI"
+readme = "README.md"
+license = "MIT"
+keywords = [
+    "jder",
+    "json",
+    "response",
+    "fastapi",
+    "python",
+]
+classifiers = [
+    "Topic :: File Formats",
+    "Topic :: File Formats :: JSON",
+    "Topic :: File Formats :: JSON :: JSON Schema",
+    "Framework :: FastAPI",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
+
+[project.urls]
+Homepage = "https://github.com/jder-std/fastapi"
+Documentation = "https://github.com/jder-std/fastapi/blob/main/docs/README.md"
+Repository = "https://github.com/jder-std/fastapi"
+Issues = "https://github.com/jder-std/fastapi/issues"
+Changelog = "https://github.com/jder-std/fastapi/blob/main/package/CHANGELOG.md"

jder_fastapi-0.1.0.dev1/src/jder_fastapi/__init__.py

@@ -0,0 +1 @@
+"""JDER FastAPI: A response builder for FastAPI"""

jder_fastapi-0.1.0.dev1/src/jder_fastapi/handlers/__init__.py

@@ -0,0 +1,5 @@
+from .validation import request_validation_exception_handler
+
+__all__ = [
+    "request_validation_exception_handler",
+]

jder_fastapi-0.1.0.dev1/src/jder_fastapi/handlers/validation/__init__.py

@@ -0,0 +1,5 @@
+from .main import request_validation_exception_handler
+
+__all__ = [
+    "request_validation_exception_handler",
+]

jder_fastapi-0.1.0.dev1/src/jder_fastapi/handlers/validation/main.py

@@ -0,0 +1,85 @@
+from typing import Sequence
+
+from fastapi.exceptions import RequestValidationError
+from fastapi.requests import Request
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, ConfigDict, TypeAdapter
+
+from jder_fastapi.responses.json import (
+    CreateJsonFailureResponseOptions,
+    JsonResponseError,
+    createJsonResponse,
+)
+
+
+class Error(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    type: str | None
+    loc: list[str] | None
+    msg: str | None
+
+
+Errors = TypeAdapter(Sequence[Error])
+
+
+def request_validation_exception_handler(
+    request: Request, exc: RequestValidationError
+) -> JSONResponse:
+    """
+    A custom exception handler for `RequestValidationError`.
+
+    ### Example
+
+    ```python
+    from fastapi import FastAPI
+    from fastapi.requests import Request
+    from fastapi.responses import JSONResponse
+    from fastapi.exceptions import RequestValidationError
+    from jder_fastapi.handlers import request_validation_exception_handler
+
+    app: FastAPI = FastAPI()
+
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_exception_handler(
+        req: Request,
+        exc: RequestValidationError,
+    ) -> JSONResponse:
+        return request_validation_exception_handler(req, exc)
+    ```
+    """
+    errs: Sequence[Error] = Errors.validate_python(exc.errors())
+
+    status: int = 400
+
+    code: str = "parse"
+
+    if len(errs) == 0:
+        return createJsonResponse(
+            options=CreateJsonFailureResponseOptions(
+                status=status,
+                errors=[
+                    JsonResponseError(
+                        code=code,
+                    )
+                ],
+            )
+        )
+
+    errors: list[JsonResponseError] = []
+
+    for err in errs:
+        errors.append(
+            JsonResponseError(
+                code=code + f".{err.type}",
+                path=err.loc,
+                message=err.msg,
+            )
+        )
+
+    return createJsonResponse(
+        options=CreateJsonFailureResponseOptions(
+            status=status,
+            errors=errors,
+        )
+    )

jder_fastapi-0.1.0.dev1/src/jder_fastapi/responses/__init__.py

@@ -0,0 +1,9 @@
+from .main import (
+    CreateResponseOptions,
+    createResponse,
+)
+
+__all__ = [
+    "CreateResponseOptions",
+    "createResponse",
+]

jder_fastapi-0.1.0.dev1/src/jder_fastapi/responses/json/__init__.py

@@ -0,0 +1,17 @@
+from .main import (
+    CreateJsonFailureResponseOptions,
+    CreateJsonResponseBaseOptions,
+    CreateJsonSuccessResponseOptions,
+    JsonResponse,
+    JsonResponseError,
+    createJsonResponse,
+)
+
+__all__ = [
+    "JsonResponseError",
+    "JsonResponse",
+    "CreateJsonResponseBaseOptions",
+    "CreateJsonSuccessResponseOptions",
+    "CreateJsonFailureResponseOptions",
+    "createJsonResponse",
+]

jder_fastapi-0.1.0.dev1/src/jder_fastapi/responses/json/main.py

@@ -0,0 +1,195 @@
+from typing import Any, Mapping, Optional, TypeVar
+
+from fastapi.responses import JSONResponse, Response
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+
+class JsonResponseError(BaseModel):
+    """
+    JSON response error.
+    """
+
+    code: str
+    """
+    Code representing the error.
+    """
+    path: Optional[list[str]] = None
+    """
+    Indicates where the error occurred.
+    """
+    message: Optional[str] = None
+    """
+    Detail of the error.
+    """
+
+
+class JsonResponse[T = Any](BaseModel):
+    """
+    JSON response.
+    """
+
+    success: bool
+    """
+    Indicates whether the response is successful or not.
+    """
+    data: Optional[T] = None
+    """
+    Requested information for the response when `success` is `true`.
+    """
+    errors: Optional[list[JsonResponseError]] = None
+    """
+    A list of errors for the response when `success` is `false`.
+    """
+
+
+class CreateJsonResponseBaseOptions(BaseModel):
+    """
+    Base options of `createJsonResponse` function.
+    """
+
+    status: Optional[int] = None
+    """
+    Status code of the response.
+    By default, it is `200` for success and `400` for failure.
+    """
+    headers: Optional[Mapping[str, str]] = None
+    """
+    Additional headers of the response.
+    """
+
+
+class CreateJsonSuccessResponseOptions[T = Any](CreateJsonResponseBaseOptions):
+    """
+    Options of `createJsonResponse` function.
+    """
+
+    data: Optional[T] = None
+    """
+    Requested information for the response when `success` is `true`.
+    """
+
+
+class CreateJsonFailureResponseOptions(CreateJsonResponseBaseOptions):
+    """
+    Options of `createJsonResponse` function.
+    """
+
+    errors: Optional[list[JsonResponseError]] = None
+    """
+    A list of errors for the response when `success` is `false`.
+    """
+
+
+def createJsonResponse(
+    response: Response | None = None,
+    options: CreateJsonSuccessResponseOptions[T]
+    | CreateJsonFailureResponseOptions
+    | None = None,
+) -> JSONResponse:
+    """
+    Create a JSON response.
+
+    ### Examples
+
+    Example for creating a successful JSON response without data:
+
+    ```python
+    from fastapi import FastAPI
+    from fastapi.responses import Response
+    from jder_fastapi.responses.json import createJsonResponse
+
+    app: FastAPI = FastAPI()
+
+
+    @app.get("/")
+    async def route() -> Response:
+        return createJsonResponse()
+    ```
+
+    Example for creating a successful JSON response with data:
+
+    ```python
+    from fastapi import FastAPI
+    from fastapi.responses import Response
+    from jder_fastapi.responses.json import createJsonResponse
+
+    app: FastAPI = FastAPI()
+
+
+    @app.get("/")
+    async def route() -> Response:
+        return createJsonResponse(
+            options={
+                "data": "Hello, World!",
+            }
+        )
+    ```
+
+    Example for creating a failure JSON response:
+
+    ```python
+    from fastapi import FastAPI
+    from fastapi.responses import Response
+    from jder_fastapi.responses.json import createJsonResponse
+
+    app: FastAPI = FastAPI()
+
+
+    @app.get("/")
+    async def route() -> Response:
+        return createJsonResponse(
+            options={
+                "status": 500,
+                "errors": [
+                    {
+                        "code": "server",
+                        "message": "Internal server error",
+                    },
+                ],
+            }
+        )
+    ```
+
+    Example for merging response:
+
+    ```python
+    from fastapi import FastAPI
+    from fastapi.responses import Response
+    from jder_fastapi.responses.json import createJsonResponse
+
+    app: FastAPI = FastAPI()
+
+
+    @app.get("/")
+    async def route(res: Response) -> Response:
+        return createJsonResponse(res)
+    ```
+    """
+    is_failure: bool = isinstance(options, CreateJsonFailureResponseOptions)
+
+    status: int = (
+        options.status
+        if options and options.status
+        else (400 if is_failure else 200)
+    )
+
+    headers: Mapping[str, str] = {
+        **(dict(response.headers) if response else {}),
+        **(options.headers if options and options.headers else {}),
+    }
+
+    body: JsonResponse[T] = JsonResponse(
+        success=not is_failure,
+        data=options.data
+        if isinstance(options, CreateJsonSuccessResponseOptions)
+        else None,
+        errors=options.errors if is_failure else None,
+    )
+
+    return JSONResponse(
+        status_code=status,
+        headers=headers,
+        content=body.model_dump(exclude_none=True),
+    )

jder_fastapi-0.1.0.dev1/src/jder_fastapi/responses/main.py

@@ -0,0 +1,76 @@
+from typing import Any, Mapping, Optional, TypeVar
+
+from fastapi.responses import Response
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+
+class CreateResponseOptions[T = Any](BaseModel):
+    """
+    Options of `createResponse` function.
+    """
+
+    status: Optional[int] = None
+    """
+    Status code of the response.
+    """
+    headers: Optional[Mapping[str, str]] = None
+    """
+    Headers of the response.
+    """
+    body: Optional[T] = None
+    """
+    Body of the response.
+    """
+
+
+def createResponse(
+    response: Response | None = None,
+    options: CreateResponseOptions[T] | None = None,
+) -> Response:
+    """
+    Create a response.
+
+    ### Example
+
+    ```python
+    from fastapi import FastAPI
+    from fastapi.responses import Response
+    from jder_fastapi.responses import createResponse
+
+    app: FastAPI = FastAPI()
+
+
+    @app.get("/")
+    async def route() -> Response:
+        return createResponse(
+            {
+                "headers": {
+                    "Content-Type": "text/plain",
+                },
+                "body": "Hello, World!",
+            },
+        )
+    ```
+    """
+    status: int = 200
+    headers: Mapping[str, str] = {}
+    body: T | None = None
+
+    if response:
+        headers = dict(response.headers or {})
+
+    if options:
+        if options.status:
+            status = options.status
+        if options.headers:
+            headers = {**headers, **options.headers}
+        if options.body:
+            body = options.body
+
+    return Response(
+        status_code=status,
+        headers=headers,
+        content=body,
+    )