wellapi 0.2.1__py3-none-any.whl

wellapi/middleware/exceptions.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import typing
+
+from wellapi.exceptions import HTTPException
+from wellapi.models import RequestAPIGateway, ResponseAPIGateway
+
+
+def _lookup_exception_handler(exc_handlers, exc: Exception):
+    for cls in type(exc).__mro__:
+        if cls in exc_handlers:
+            return exc_handlers[cls]
+    return None
+
+
+class ExceptionMiddleware:
+    def __init__(
+        self,
+        next_call: typing.Callable,
+        handlers: typing.Mapping[
+            typing.Any,
+            typing.Callable[[RequestAPIGateway, Exception], ResponseAPIGateway],
+        ]
+        | None = None,
+        debug: bool = False,
+    ) -> None:
+        self.next_call = next_call
+        self.debug = debug  # TODO: We ought to handle 404 cases if debug is set.
+        self._status_handlers = {}
+        self._exception_handlers = {
+            HTTPException: self.http_exception,
+        }
+        if handlers is not None:  # pragma: no branch
+            for key, value in handlers.items():
+                self.add_exception_handler(key, value)
+
+    def add_exception_handler(
+        self,
+        exc_class_or_status_code: int | type[Exception],
+        handler: typing.Callable[[RequestAPIGateway, Exception], ResponseAPIGateway],
+    ) -> None:
+        if isinstance(exc_class_or_status_code, int):
+            self._status_handlers[exc_class_or_status_code] = handler
+        else:
+            assert issubclass(exc_class_or_status_code, Exception)
+            self._exception_handlers[exc_class_or_status_code] = handler
+
+    def __call__(self, request: RequestAPIGateway) -> ResponseAPIGateway:
+        try:
+            response = self.next_call(request)
+        except Exception as exc:
+            handler = None
+
+            if isinstance(exc, HTTPException):
+                handler = self._status_handlers.get(exc.status_code)
+
+            if handler is None:
+                handler = _lookup_exception_handler(self._exception_handlers, exc)
+
+            if handler is None:
+                raise exc
+
+            response = handler(request, exc)
+
+        return response
+
+    def http_exception(
+        self, _: RequestAPIGateway, exc: Exception
+    ) -> ResponseAPIGateway:
+        assert isinstance(exc, HTTPException)
+
+        return ResponseAPIGateway(
+            exc.detail, status_code=exc.status_code, headers=exc.headers
+        )

wellapi/middleware/main.py

@@ -0,0 +1,26 @@
+from collections.abc import Iterator
+from typing import Any
+
+
+class Middleware:
+    def __init__(
+        self,
+        cls,
+        *args,
+        **kwargs,
+    ) -> None:
+        self.cls = cls
+        self.args = args
+        self.kwargs = kwargs
+
+    def __iter__(self) -> Iterator[Any]:
+        as_tuple = (self.cls, self.args, self.kwargs)
+        return iter(as_tuple)
+
+    def __repr__(self) -> str:
+        class_name = self.__class__.__name__
+        args_strings = [f"{value!r}" for value in self.args]
+        option_strings = [f"{key}={value!r}" for key, value in self.kwargs.items()]
+        name = getattr(self.cls, "__name__", "")
+        args_repr = ", ".join([name] + args_strings + option_strings)
+        return f"{class_name}({args_repr})"

wellapi/models.py

@@ -0,0 +1,150 @@
+import json
+import typing
+
+from wellapi.datastructures import Headers, MutableHeaders, QueryParams
+
+
+class RequestAPIGateway:
+    """
+    https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html#http-api-develop-integrations-lambda.proxy-format
+    """
+
+    def __init__(self, path_params, query_params, headers, body, cookies):
+        self.path_params = path_params
+        self.query_params = QueryParams(query_params)
+        self.headers = Headers(raw=headers)
+        self.cookies = cookies
+        self._body = body
+
+    def json(self):
+        """
+        Returns the request body as JSON.
+        """
+        if not self._body:
+            return None
+
+        return json.loads(self._body)
+
+    @classmethod
+    def create_request_from_event(cls, event):
+        """
+        Create a RequestAPIGateway object from the AWS API Gateway event.
+        """
+        path_params = event.get("pathParameters", {})
+        multi_query_params = event.get("multiValueQueryStringParameters", {})
+        multi_headers = event.get("multiValueHeaders", {})
+        body = event.get("body", "")
+        cookies = event.get("cookies", {})
+
+        headers = []
+        for h_name, h_value in multi_headers.items():
+            if isinstance(h_value, list):
+                for h in h_value:
+                    headers.append(
+                        (h_name.lower().encode("latin-1"), h.encode("latin-1"))
+                    )
+            else:
+                headers.append(
+                    (h_name.lower().encode("latin-1"), h_value.encode("latin-1"))
+                )
+
+        query_params = []
+        for q_name, q_value in multi_query_params.items():
+            if isinstance(q_value, list):
+                for q in q_value:
+                    query_params.append((q_name, q))
+            else:
+                query_params.append((q_name, q_value))
+
+        return cls(path_params, query_params, headers, body, cookies)
+
+
+class ResponseAPIGateway:
+    isBase64Encoded: bool = False
+
+    def __init__(
+        self,
+        content: typing.Any = None,
+        status_code: int = 200,
+        headers: typing.Mapping[str, str] | None = None,
+    ) -> None:
+        self.statusCode = status_code
+        self.body = content
+        self.raw_headers = headers
+
+    @property
+    def headers(self) -> MutableHeaders:
+        if not hasattr(self, "_headers"):
+            self._headers = MutableHeaders(headers=self.raw_headers)
+        return self._headers
+
+    def to_aws_response(self):
+        if isinstance(self.body, str):
+            body = self.body
+        else:
+            body = json.dumps(self.body)
+
+        return {
+            "statusCode": self.statusCode,
+            "headers": dict(self.headers),
+            "body": body,
+            "isBase64Encoded": self.isBase64Encoded,
+        }
+
+
+class RequestSQS:
+    """
+    https://docs.aws.amazon.com/lambda/latest/dg/with-sqs-example.html#with-sqs-create-test-function
+    """
+
+    def __init__(self, records: list[dict[str, typing.Any]]):
+        self._records = records
+        self.path_params = None
+        self.query_params = None
+        self.headers = None
+        self.cookies = None
+
+    @classmethod
+    def create_request_from_event(cls, event):
+        """
+        Create a RequestAPIGateway object from the AWS API Gateway event.
+        """
+
+        return cls(event["Records"])
+
+    def json(self):
+        """
+        Returns the request body as JSON.
+        """
+        if not self._records:
+            return None
+
+        body = []
+        for record in self._records:
+            body.append(json.loads(record.get("body")))
+
+        return body
+
+
+class RequestJob:
+    """
+    https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-run-lambda-schedule.html#eb-schedule-create-rule
+    """
+
+    def __init__(self, event: dict[str, typing.Any]):
+        self._event = event
+        self.path_params = None
+        self.query_params = None
+        self.headers = None
+        self.cookies = None
+
+    @classmethod
+    def create_request_from_event(cls, event):
+        """
+        Create a RequestAPIGateway object from the AWS API Gateway event.
+        """
+
+        return cls(event)
+
+    def json(self):
+        return None

wellapi/openapi/docs.py

@@ -0,0 +1,344 @@
+import json
+from typing import Annotated, Any
+
+from fastapi.encoders import jsonable_encoder
+from starlette.responses import HTMLResponse
+from typing_extensions import Doc
+
+swagger_ui_default_parameters: Annotated[
+    dict[str, Any],
+    Doc(
+        """
+        Default configurations for Swagger UI.
+
+        You can use it as a template to add any other configurations needed.
+        """
+    ),
+] = {
+    "dom_id": "#swagger-ui",
+    "layout": "BaseLayout",
+    "deepLinking": True,
+    "showExtensions": True,
+    "showCommonExtensions": True,
+}
+
+
+def get_swagger_ui_html(
+    *,
+    openapi_url: Annotated[
+        str,
+        Doc(
+            """
+            The OpenAPI URL that Swagger UI should load and use.
+
+            This is normally done automatically by FastAPI using the default URL
+            `/openapi.json`.
+            """
+        ),
+    ],
+    title: Annotated[
+        str,
+        Doc(
+            """
+            The HTML `<title>` content, normally shown in the browser tab.
+            """
+        ),
+    ],
+    swagger_js_url: Annotated[
+        str,
+        Doc(
+            """
+            The URL to use to load the Swagger UI JavaScript.
+
+            It is normally set to a CDN URL.
+            """
+        ),
+    ] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js",
+    swagger_css_url: Annotated[
+        str,
+        Doc(
+            """
+            The URL to use to load the Swagger UI CSS.
+
+            It is normally set to a CDN URL.
+            """
+        ),
+    ] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css",
+    swagger_favicon_url: Annotated[
+        str,
+        Doc(
+            """
+            The URL of the favicon to use. It is normally shown in the browser tab.
+            """
+        ),
+    ] = "https://fastapi.tiangolo.com/img/favicon.png",
+    oauth2_redirect_url: Annotated[
+        str | None,
+        Doc(
+            """
+            The OAuth2 redirect URL, it is normally automatically handled by FastAPI.
+            """
+        ),
+    ] = None,
+    init_oauth: Annotated[
+        dict[str, Any] | None,
+        Doc(
+            """
+            A dictionary with Swagger UI OAuth2 initialization configurations.
+            """
+        ),
+    ] = None,
+    swagger_ui_parameters: Annotated[
+        dict[str, Any] | None,
+        Doc(
+            """
+            Configuration parameters for Swagger UI.
+
+            It defaults to [swagger_ui_default_parameters][fastapi.openapi.docs.swagger_ui_default_parameters].
+            """
+        ),
+    ] = None,
+) -> HTMLResponse:
+    """
+    Generate and return the HTML  that loads Swagger UI for the interactive
+    API docs (normally served at `/docs`).
+
+    You would only call this function yourself if you needed to override some parts,
+    for example the URLs to use to load Swagger UI's JavaScript and CSS.
+
+    Read more about it in the
+    [FastAPI docs for Configure Swagger UI](https://fastapi.tiangolo.com/how-to/configure-swagger-ui/)
+    and the [FastAPI docs for Custom Docs UI Static Assets (Self-Hosting)](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/).
+    """
+    current_swagger_ui_parameters = swagger_ui_default_parameters.copy()
+    if swagger_ui_parameters:
+        current_swagger_ui_parameters.update(swagger_ui_parameters)
+
+    html = f"""
+    <!DOCTYPE html>
+    <html>
+    <head>
+    <link type="text/css" rel="stylesheet" href="{swagger_css_url}">
+    <link rel="shortcut icon" href="{swagger_favicon_url}">
+    <title>{title}</title>
+    </head>
+    <body>
+    <div id="swagger-ui">
+    </div>
+    <script src="{swagger_js_url}"></script>
+    <!-- `SwaggerUIBundle` is now available on the page -->
+    <script>
+    const ui = SwaggerUIBundle({{
+        url: '{openapi_url}',
+    """
+
+    for key, value in current_swagger_ui_parameters.items():
+        html += f"{json.dumps(key)}: {json.dumps(jsonable_encoder(value))},\n"
+
+    if oauth2_redirect_url:
+        html += f"oauth2RedirectUrl: window.location.origin + '{oauth2_redirect_url}',"
+
+    html += """
+    presets: [
+        SwaggerUIBundle.presets.apis,
+        SwaggerUIBundle.SwaggerUIStandalonePreset
+        ],
+    })"""
+
+    if init_oauth:
+        html += f"""
+        ui.initOAuth({json.dumps(jsonable_encoder(init_oauth))})
+        """
+
+    html += """
+    </script>
+    </body>
+    </html>
+    """
+    return HTMLResponse(html)
+
+
+def get_redoc_html(
+    *,
+    openapi_url: Annotated[
+        str,
+        Doc(
+            """
+            The OpenAPI URL that ReDoc should load and use.
+
+            This is normally done automatically by FastAPI using the default URL
+            `/openapi.json`.
+            """
+        ),
+    ],
+    title: Annotated[
+        str,
+        Doc(
+            """
+            The HTML `<title>` content, normally shown in the browser tab.
+            """
+        ),
+    ],
+    redoc_js_url: Annotated[
+        str,
+        Doc(
+            """
+            The URL to use to load the ReDoc JavaScript.
+
+            It is normally set to a CDN URL.
+            """
+        ),
+    ] = "https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js",
+    redoc_favicon_url: Annotated[
+        str,
+        Doc(
+            """
+            The URL of the favicon to use. It is normally shown in the browser tab.
+            """
+        ),
+    ] = "https://fastapi.tiangolo.com/img/favicon.png",
+    with_google_fonts: Annotated[
+        bool,
+        Doc(
+            """
+            Load and use Google Fonts.
+            """
+        ),
+    ] = True,
+) -> HTMLResponse:
+    """
+    Generate and return the HTML response that loads ReDoc for the alternative
+    API docs (normally served at `/redoc`).
+
+    You would only call this function yourself if you needed to override some parts,
+    for example the URLs to use to load ReDoc's JavaScript and CSS.
+
+    Read more about it in the
+    [FastAPI docs for Custom Docs UI Static Assets (Self-Hosting)](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/).
+    """
+    html = f"""
+    <!DOCTYPE html>
+    <html>
+    <head>
+    <title>{title}</title>
+    <!-- needed for adaptive design -->
+    <meta charset="utf-8"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    """
+    if with_google_fonts:
+        html += """
+    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+    """
+    html += f"""
+    <link rel="shortcut icon" href="{redoc_favicon_url}">
+    <!--
+    ReDoc doesn't change outer page styles
+    -->
+    <style>
+      body {{
+        margin: 0;
+        padding: 0;
+      }}
+    </style>
+    </head>
+    <body>
+    <noscript>
+        ReDoc requires Javascript to function. Please enable it to browse the documentation.
+    </noscript>
+    <redoc spec-url="{openapi_url}"></redoc>
+    <script src="{redoc_js_url}"> </script>
+    </body>
+    </html>
+    """
+    return HTMLResponse(html)
+
+
+def get_swagger_ui_oauth2_redirect_html() -> HTMLResponse:
+    """
+    Generate the HTML response with the OAuth2 redirection for Swagger UI.
+
+    You normally don't need to use or change this.
+    """
+    # copied from https://github.com/swagger-api/swagger-ui/blob/v4.14.0/dist/oauth2-redirect.html
+    html = """
+    <!doctype html>
+    <html lang="en-US">
+    <head>
+        <title>Swagger UI: OAuth2 Redirect</title>
+    </head>
+    <body>
+    <script>
+        'use strict';
+        function run () {
+            var oauth2 = window.opener.swaggerUIRedirectOauth2;
+            var sentState = oauth2.state;
+            var redirectUrl = oauth2.redirectUrl;
+            var isValid, qp, arr;
+
+            if (/code|token|error/.test(window.location.hash)) {
+                qp = window.location.hash.substring(1).replace('?', '&');
+            } else {
+                qp = location.search.substring(1);
+            }
+
+            arr = qp.split("&");
+            arr.forEach(function (v,i,_arr) { _arr[i] = '"' + v.replace('=', '":"') + '"';});
+            qp = qp ? JSON.parse('{' + arr.join() + '}',
+                    function (key, value) {
+                        return key === "" ? value : decodeURIComponent(value);
+                    }
+            ) : {};
+
+            isValid = qp.state === sentState;
+
+            if ((
+              oauth2.auth.schema.get("flow") === "accessCode" ||
+              oauth2.auth.schema.get("flow") === "authorizationCode" ||
+              oauth2.auth.schema.get("flow") === "authorization_code"
+            ) && !oauth2.auth.code) {
+                if (!isValid) {
+                    oauth2.errCb({
+                        authId: oauth2.auth.name,
+                        source: "auth",
+                        level: "warning",
+                        message: "Authorization may be unsafe, passed state was changed in server. The passed state wasn't returned from auth server."
+                    });
+                }
+
+                if (qp.code) {
+                    delete oauth2.state;
+                    oauth2.auth.code = qp.code;
+                    oauth2.callback({auth: oauth2.auth, redirectUrl: redirectUrl});
+                } else {
+                    let oauthErrorMsg;
+                    if (qp.error) {
+                        oauthErrorMsg = "["+qp.error+"]: " +
+                            (qp.error_description ? qp.error_description+ ". " : "no accessCode received from the server. ") +
+                            (qp.error_uri ? "More info: "+qp.error_uri : "");
+                    }
+
+                    oauth2.errCb({
+                        authId: oauth2.auth.name,
+                        source: "auth",
+                        level: "error",
+                        message: oauthErrorMsg || "[Authorization failed]: no accessCode received from the server."
+                    });
+                }
+            } else {
+                oauth2.callback({auth: oauth2.auth, token: qp, isValid: isValid, redirectUrl: redirectUrl});
+            }
+            window.close();
+        }
+
+        if (document.readyState !== 'loading') {
+            run();
+        } else {
+            document.addEventListener('DOMContentLoaded', function () {
+                run();
+            });
+        }
+    </script>
+    </body>
+    </html>
+        """
+    return HTMLResponse(content=html)