bareASGI-rest 5.0.0__py3-none-any.whl

bareasgi_rest/__init__.py

@@ -0,0 +1,14 @@
+"""Enhanced REST support for bareASGI"""
+
+from .rest_application import RestApplication
+from .rest_router import RestHttpRouter
+from .swagger.config import SwaggerConfig, SwaggerOauth2Config
+from .types import RestError
+
+__all__ = [
+    "RestApplication",
+    "RestHttpRouter",
+    "RestError",
+    "SwaggerConfig",
+    "SwaggerOauth2Config"
+]

bareasgi_rest/arg_builder.py

@@ -0,0 +1,93 @@
+"""Argument builder"""
+
+from inspect import Parameter, Signature
+from typing import Any, Awaitable, Callable, get_args
+
+from jetblack_serialization.custom_annotations import (
+    is_any_serialization_annotation
+)
+
+from jetblack_serialization import typing_ex
+
+from .types import ArgDeserializer
+
+
+def is_optional_list(annotation: Any) -> bool:
+    if not typing_ex.is_optional(annotation):
+        return False
+    optional_types = typing_ex.get_optional_types(annotation)
+    if len(optional_types) != 1:
+        return False
+    return typing_ex.is_list(optional_types[0])
+
+
+async def make_args(
+        signature: Signature,
+        matches: dict[str, str],
+        query: dict[str, list[str]],
+        body: Callable[[Any], Awaitable[Any]],
+        arg_deserializer: ArgDeserializer
+) -> tuple[tuple[Any, ...], dict[str, Any]]:
+    """Make args and kwargs for the given signature from the route matches,
+    query args and body.
+
+    Args:
+        signature (Signature): The function signature
+        matches (dict[str, str]): The route matches
+        query (dict[str, Any]): A dictionary built from the query string
+        body (Callable[[AsyncIterator[bytes], Any], Any]): Get the body
+        arg_deserializer (ArgDeserializer): A deserializer for args
+
+    Raises:
+        KeyError: If a parameter was not found
+
+    Returns:
+        tuple[tuple[Any, ...], dict[str, Any]]: A tuple for *args and **kwargs
+    """
+
+    kwargs: dict[str, Any] = {}
+    args: list[Any] = []
+
+    for parameter in signature.parameters.values():
+        if is_any_serialization_annotation(parameter.annotation):
+            value: Any = await body(parameter.annotation)
+        else:
+            if parameter.name in matches:
+                value = arg_deserializer(
+                    matches[parameter.name],
+                    parameter.annotation
+                )
+            elif parameter.name in query:
+                if typing_ex.is_list(
+                        parameter.annotation
+                ) or is_optional_list(
+                    parameter.annotation
+                ):
+                    element_type, *_rest = get_args(parameter.annotation)
+                    value = [
+                        arg_deserializer(item, element_type)
+                        for item in query[parameter.name]
+                    ]
+                else:
+                    value = arg_deserializer(
+                        query[parameter.name][0],
+                        parameter.annotation
+                    )
+
+            elif typing_ex.is_optional(parameter.annotation):
+                value = None
+            else:
+                raise KeyError(parameter.name)
+
+        if (
+                parameter.kind == Parameter.POSITIONAL_ONLY
+                or parameter.kind == Parameter.POSITIONAL_OR_KEYWORD
+        ):
+            args.append(value)
+        else:
+            kwargs[parameter.name] = value
+
+    bound_args = signature.bind(*args, **kwargs)
+    bound_args.apply_defaults()
+
+    return bound_args.args, bound_args.kwargs

bareasgi_rest/constants.py

@@ -0,0 +1,69 @@
+"""Constants"""
+
+from bareasgi import HttpResponse, text_writer
+from stringcase import camelcase, snakecase, pascalcase
+
+from jetblack_serialization import SerializerConfig
+
+from .types import (
+    DictConsumes,
+    DictProduces,
+    DictSerializerConfig
+)
+
+from .serialization.json import (
+    to_json,
+    from_json,
+    from_form_data,
+    from_query_string,
+    json_arg_deserializer_factory
+)
+from .serialization.xml import from_xml, to_xml
+from .swagger import SwaggerConfig
+
+DEFAULT_SWAGGER_BASE_URL = "https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.4.0"
+DEFAULT_TYPEFACE_URL = "https://fonts.googleapis.com/css?family=Roboto:300,400,500,700&display=swap"
+
+DEFAULT_CONSUMES: DictConsumes = {
+    b'application/json': from_json,
+    b'application/x-www-form-urlencoded': from_query_string,
+    b'multipart/form-data': from_form_data,
+    b'application/xml': from_xml,
+    b'*/*': from_json,
+}
+
+DEFAULT_PRODUCES: DictProduces = {
+    b'application/json': to_json,
+    b'application/xml': to_xml,
+    b'*/*': to_json,
+}
+
+DEFAULT_COLLECTION_FORMAT = 'multi'
+
+DEFAULT_NOT_FOUND_RESPONSE: HttpResponse = HttpResponse(
+    404,
+    [(b'content-type', b'text/plain')],
+    text_writer('Not Found')
+)
+
+DEFAULT_JSON_SERIALIZER_CONFIG = SerializerConfig(
+    key_serializer=camelcase,
+    key_deserializer=snakecase
+)
+DEFAULT_XML_SERIALIZER_CONFIG = SerializerConfig(
+    key_serializer=pascalcase,
+    key_deserializer=snakecase
+)
+
+DEFAULT_SERIALIZER_CONFIG: DictSerializerConfig = {
+    b'application/json': DEFAULT_JSON_SERIALIZER_CONFIG,
+    b'*/*': DEFAULT_JSON_SERIALIZER_CONFIG,
+    b'application/xml': DEFAULT_XML_SERIALIZER_CONFIG,
+}
+
+DEFAULT_ARG_DESERIALIZER_FACTORY = json_arg_deserializer_factory
+
+DEFAULT_SWAGGER_CONFIG = SwaggerConfig(
+    serialize_key=camelcase,
+    deserialize_key=snakecase
+)

bareasgi_rest/rest_application.py

@@ -0,0 +1,150 @@
+from typing import Any, Callable, Final, Sequence, cast
+
+from jetblack_serialization.config import SerializerConfig
+
+from bareasgi import (
+    Application,
+    HttpMiddlewares,
+    HttpResponse,
+    LifespanRequestHandler,
+    WebSocketMiddlewares,
+    WebSocketRouter,
+)
+from bareutils import text_writer
+from bareutils import response_code
+
+from .constants import DEFAULT_COLLECTION_FORMAT
+from .rest_router import RestHttpRouter
+from .types import ArgDeserializerFactory, DictSerializerConfig, RestCallback
+
+
+DEFAULT_NOT_FOUND_RESPONSE: Final[HttpResponse] = HttpResponse(
+    response_code.NOT_FOUND,
+    [(b'content-type', b'text/plain')],
+    text_writer('Not Found')
+)
+
+
+class RestApplication(Application):
+
+    def __init__(
+            self,
+            *,
+            middlewares: HttpMiddlewares | None = None,
+            rest_router: RestHttpRouter | None = None,
+            ws_middlewares: WebSocketMiddlewares | None = None,
+            ws_router: WebSocketRouter | None = None,
+            startup_handlers: list[LifespanRequestHandler] | None = None,
+            shutdown_handlers: list[LifespanRequestHandler] | None = None,
+            not_found_response: HttpResponse = DEFAULT_NOT_FOUND_RESPONSE,
+            info: dict[str, Any] | None = None
+    ) -> None:
+        """Construct the application
+
+        ```python
+        from bareasgi import (
+            Application,
+            Scope,
+            HttpRequest,
+            HttpResponse,
+            text_reader,
+            text_writer
+        )
+
+        async def http_request_callback(request: HttpRequest) -> HttpResponse:
+            text = await text_reader(request.body)
+            return HttpResponse(
+                200,
+                [(b'content-type', b'text/plain')],
+                text_writer('This is not a test')
+            )
+
+        import uvicorn
+
+        app = Application()
+        app.http_router.add({'GET', 'POST', 'PUT', 'DELETE'}, '/{path}', http_request_callback)
+
+        uvicorn.run(app, port=9009)
+        ```
+
+        Args:
+            middlewares (HttpMiddlewares | None, optional): Optional
+                middleware callbacks. Defaults to None.
+            rest_router (RestHttpRouter | None, optional): Optional router to for
+                http routes. Defaults to None.
+            ws_middlewares (WebSocketMiddlewares | None, optional):
+                Optional middleware callbacks. Defaults to None.
+            ws_router (WebSocketRouter | None, optional): Optional
+                router for web routes. Defaults to None.
+            startup_handlers (list[LifespanHandler] | None, optional): Optional
+                handlers to run at startup. Defaults to None.
+            shutdown_handlers (list[LifespanHandler] | None, optional): Optional
+                handlers to run at shutdown. Defaults to None.
+            not_found_response (HttpResponse | None, optional): Optional not
+                found (404) response. Defaults to DEFAULT_NOT_FOUND_RESPONSE.
+            info (dict[str, Any] | None, optional): Optional
+                dictionary for user data. Defaults to None.
+        """
+        super().__init__(
+            middlewares=middlewares,
+            http_router=rest_router,
+            ws_middlewares=ws_middlewares,
+            ws_router=ws_router,
+            startup_handlers=startup_handlers,
+            shutdown_handlers=shutdown_handlers,
+            not_found_response=not_found_response,
+            info=info
+        )
+
+    @property
+    def rest_router(self) -> RestHttpRouter:
+        """Get the REST router
+
+        Returns:
+            RestHttpRouter: The REST router
+        """
+        return cast(RestHttpRouter, self.http_router)
+
+    def on_rest_request(
+            self,
+            methods: set[str],
+            path: str,
+            *,
+            consumes: Sequence[bytes] | None = None,
+            produces: Sequence[bytes] | None = None,
+            collection_format: str = DEFAULT_COLLECTION_FORMAT,
+            tags: list[str] | None = None,
+            status_code: int = response_code.OK,
+            status_description: str = 'OK',
+            serializer_config: DictSerializerConfig | None = None,
+            arg_serializer_config: SerializerConfig | None = None,
+            arg_deserializer_factory: ArgDeserializerFactory | None = None
+    ) -> Callable[[RestCallback], RestCallback]:
+        """A decorator to add an http rest route handler to the application
+
+        Args:
+            methods (AbstractSet[str]): The http methods, e.g. {{'POST', 'PUT'}
+            path (str): The path
+
+        Returns:
+            Callable[[HttpRequestCallback], HttpRequestCallback]: The decorated
+                request.
+        """
+        def decorator(callback: RestCallback) -> Callable:
+            self.rest_router.add_rest(
+                methods,
+                path,
+                callback,
+                consumes=consumes,
+                produces=produces,
+                collection_format=collection_format,
+                tags=tags,
+                status_code=status_code,
+                status_description=status_description,
+                serializer_config=serializer_config,
+                arg_serializer_config=arg_serializer_config,
+                arg_deserializer_factory=arg_deserializer_factory
+            )
+            return callback
+
+        return decorator