qena-shared-lib 0.1.0__py3-none-any.whl

qena_shared_lib/http.py

@@ -0,0 +1,631 @@
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Callable, Sequence, TypeVar
+
+from fastapi import APIRouter, Response
+from fastapi.datastructures import Default
+from fastapi.params import Depends
+from fastapi.responses import JSONResponse
+from fastapi.types import IncEx
+
+__all__ = [
+    "ApiController",
+    "ControllerBase",
+    "delete",
+    "get",
+    "head",
+    "options",
+    "patch",
+    "post",
+    "put",
+    "trace",
+]
+
+AC = TypeVar("AC")
+API_CONTROLLER_ATTRIBUTE = "__api_controller_router__"
+ROUTE_HANDLER_ATTRIBUTE = "__route_handler_meta__"
+
+
+class HTTPMethods(Enum):
+    GET = 0
+    PUT = 1
+    POST = 2
+    DELETE = 3
+    OPTIONS = 4
+    HEAD = 5
+    PATCH = 6
+    TRACE = 7
+
+
+@dataclass
+class RouteHandlerMeta:
+    method: HTTPMethods
+    path: str | None = None
+    response_model: Any | None = Default(None)
+    status_code: int | None = None
+    tags: list[str | Enum] | None = None
+    dependencies: Sequence[Depends] | None = None
+    summary: str | None = None
+    description: str | None = None
+    response_description: str = "Successful Response"
+    responses: dict[int | str, dict[str, Any]] | None = None
+    deprecated: bool | None = None
+    response_model_include: IncEx | None = None
+    response_model_exclude: IncEx | None = None
+    response_model_by_alias: bool = True
+    response_model_exclude_unset: bool = False
+    response_model_exclude_defaults: bool = False
+    response_model_exclude_none: bool = False
+    include_in_schema: bool = True
+    response_class: type[Response] = Default(JSONResponse)
+    name: str | None = None
+    openapi_extra: dict[str, Any] | None = None
+
+
+class ApiController:
+    def __init__(
+        self,
+        prefix: str | None = None,
+        *,
+        tags: list[str | Enum] | None = None,
+        dependencies: Sequence[Depends] | None = None,
+        default_response_class: type[Response] = Default(JSONResponse),
+        responses: dict[int | str, dict[str, Any]] | None = None,
+        redirect_slashes: bool = True,
+        deprecated: bool | None = None,
+        include_in_schema: bool = True,
+    ):
+        self._api_router = APIRouter(
+            prefix=prefix or "",
+            tags=tags,
+            dependencies=dependencies,
+            default_response_class=default_response_class,
+            responses=responses,
+            redirect_slashes=redirect_slashes,
+            deprecated=deprecated,
+            include_in_schema=include_in_schema,
+        )
+
+    def __call__(self, controller: type[AC]) -> type[AC]:
+        setattr(controller, API_CONTROLLER_ATTRIBUTE, self._api_router)
+
+        return controller
+
+
+def get(
+    path: str | None = None,
+    *,
+    response_model: Any | None = Default(None),
+    status_code: int | None = None,
+    tags: list[str | Enum] | None = None,
+    dependencies: Sequence[Depends] | None = None,
+    summary: str | None = None,
+    description: str | None = None,
+    response_description: str = "Successful Response",
+    responses: dict[int | str, dict[str, Any]] | None = None,
+    deprecated: bool | None = None,
+    response_model_include: IncEx | None = None,
+    response_model_exclude: IncEx | None = None,
+    response_model_by_alias: bool = True,
+    response_model_exclude_unset: bool = False,
+    response_model_exclude_defaults: bool = False,
+    response_model_exclude_none: bool = False,
+    include_in_schema: bool = True,
+    response_class: type[Response] = Default(JSONResponse),
+    name: str | None = None,
+    openapi_extra: dict[str, Any] | None = None,
+) -> Callable[[Callable], Callable]:
+    def wrapper(route_handler: Callable) -> Callable:
+        setattr(
+            route_handler,
+            ROUTE_HANDLER_ATTRIBUTE,
+            RouteHandlerMeta(
+                method=HTTPMethods.GET,
+                path=path,
+                response_model=response_model,
+                status_code=status_code,
+                tags=tags,
+                dependencies=dependencies,
+                summary=summary,
+                description=description,
+                response_description=response_description,
+                responses=responses,
+                deprecated=deprecated,
+                response_model_include=response_model_include,
+                response_model_exclude=response_model_exclude,
+                response_model_by_alias=response_model_by_alias,
+                response_model_exclude_unset=response_model_exclude_unset,
+                response_model_exclude_defaults=response_model_exclude_defaults,
+                response_model_exclude_none=response_model_exclude_none,
+                include_in_schema=include_in_schema,
+                response_class=response_class,
+                name=name,
+                openapi_extra=openapi_extra,
+            ),
+        )
+
+        return route_handler
+
+    return wrapper
+
+
+def put(
+    path: str | None = None,
+    *,
+    response_model: Any | None = Default(None),
+    status_code: int | None = None,
+    tags: list[str | Enum] | None = None,
+    dependencies: Sequence[Depends] | None = None,
+    summary: str | None = None,
+    description: str | None = None,
+    response_description: str = "Successful Response",
+    responses: dict[int | str, dict[str, Any]] | None = None,
+    deprecated: bool | None = None,
+    response_model_include: IncEx | None = None,
+    response_model_exclude: IncEx | None = None,
+    response_model_by_alias: bool = True,
+    response_model_exclude_unset: bool = False,
+    response_model_exclude_defaults: bool = False,
+    response_model_exclude_none: bool = False,
+    include_in_schema: bool = True,
+    response_class: type[Response] = Default(JSONResponse),
+    name: str | None = None,
+    openapi_extra: dict[str, Any] | None = None,
+) -> Callable[[Callable], Callable]:
+    def wrapper(route_handler: Callable) -> Callable:
+        setattr(
+            route_handler,
+            ROUTE_HANDLER_ATTRIBUTE,
+            RouteHandlerMeta(
+                method=HTTPMethods.PUT,
+                path=path,
+                response_model=response_model,
+                status_code=status_code,
+                tags=tags,
+                dependencies=dependencies,
+                summary=summary,
+                description=description,
+                response_description=response_description,
+                responses=responses,
+                deprecated=deprecated,
+                response_model_include=response_model_include,
+                response_model_exclude=response_model_exclude,
+                response_model_by_alias=response_model_by_alias,
+                response_model_exclude_unset=response_model_exclude_unset,
+                response_model_exclude_defaults=response_model_exclude_defaults,
+                response_model_exclude_none=response_model_exclude_none,
+                include_in_schema=include_in_schema,
+                response_class=response_class,
+                name=name,
+                openapi_extra=openapi_extra,
+            ),
+        )
+
+        return route_handler
+
+    return wrapper
+
+
+def post(
+    path: str | None = None,
+    *,
+    response_model: Any | None = Default(None),
+    status_code: int | None = None,
+    tags: list[str | Enum] | None = None,
+    dependencies: Sequence[Depends] | None = None,
+    summary: str | None = None,
+    description: str | None = None,
+    response_description: str = "Successful Response",
+    responses: dict[int | str, dict[str, Any]] | None = None,
+    deprecated: bool | None = None,
+    response_model_include: IncEx | None = None,
+    response_model_exclude: IncEx | None = None,
+    response_model_by_alias: bool = True,
+    response_model_exclude_unset: bool = False,
+    response_model_exclude_defaults: bool = False,
+    response_model_exclude_none: bool = False,
+    include_in_schema: bool = True,
+    response_class: type[Response] = Default(JSONResponse),
+    name: str | None = None,
+    openapi_extra: dict[str, Any] | None = None,
+) -> Callable[[Callable], Callable]:
+    def wrapper(route_handler: Callable) -> Callable:
+        setattr(
+            route_handler,
+            ROUTE_HANDLER_ATTRIBUTE,
+            RouteHandlerMeta(
+                method=HTTPMethods.POST,
+                path=path,
+                response_model=response_model,
+                status_code=status_code,
+                tags=tags,
+                dependencies=dependencies,
+                summary=summary,
+                description=description,
+                response_description=response_description,
+                responses=responses,
+                deprecated=deprecated,
+                response_model_include=response_model_include,
+                response_model_exclude=response_model_exclude,
+                response_model_by_alias=response_model_by_alias,
+                response_model_exclude_unset=response_model_exclude_unset,
+                response_model_exclude_defaults=response_model_exclude_defaults,
+                response_model_exclude_none=response_model_exclude_none,
+                include_in_schema=include_in_schema,
+                response_class=response_class,
+                name=name,
+                openapi_extra=openapi_extra,
+            ),
+        )
+
+        return route_handler
+
+    return wrapper
+
+
+def delete(
+    path: str | None = None,
+    *,
+    response_model: Any | None = Default(None),
+    status_code: int | None = None,
+    tags: list[str | Enum] | None = None,
+    dependencies: Sequence[Depends] | None = None,
+    summary: str | None = None,
+    description: str | None = None,
+    response_description: str = "Successful Response",
+    responses: dict[int | str, dict[str, Any]] | None = None,
+    deprecated: bool | None = None,
+    response_model_include: IncEx | None = None,
+    response_model_exclude: IncEx | None = None,
+    response_model_by_alias: bool = True,
+    response_model_exclude_unset: bool = False,
+    response_model_exclude_defaults: bool = False,
+    response_model_exclude_none: bool = False,
+    include_in_schema: bool = True,
+    response_class: type[Response] = Default(JSONResponse),
+    name: str | None = None,
+    openapi_extra: dict[str, Any] | None = None,
+) -> Callable[[Callable], Callable]:
+    def wrapper(route_handler: Callable) -> Callable:
+        setattr(
+            route_handler,
+            ROUTE_HANDLER_ATTRIBUTE,
+            RouteHandlerMeta(
+                method=HTTPMethods.DELETE,
+                path=path,
+                response_model=response_model,
+                status_code=status_code,
+                tags=tags,
+                dependencies=dependencies,
+                summary=summary,
+                description=description,
+                response_description=response_description,
+                responses=responses,
+                deprecated=deprecated,
+                response_model_include=response_model_include,
+                response_model_exclude=response_model_exclude,
+                response_model_by_alias=response_model_by_alias,
+                response_model_exclude_unset=response_model_exclude_unset,
+                response_model_exclude_defaults=response_model_exclude_defaults,
+                response_model_exclude_none=response_model_exclude_none,
+                include_in_schema=include_in_schema,
+                response_class=response_class,
+                name=name,
+                openapi_extra=openapi_extra,
+            ),
+        )
+
+        return route_handler
+
+    return wrapper
+
+
+def options(
+    path: str | None = None,
+    *,
+    response_model: Any | None = Default(None),
+    status_code: int | None = None,
+    tags: list[str | Enum] | None = None,
+    dependencies: Sequence[Depends] | None = None,
+    summary: str | None = None,
+    description: str | None = None,
+    response_description: str = "Successful Response",
+    responses: dict[int | str, dict[str, Any]] | None = None,
+    deprecated: bool | None = None,
+    response_model_include: IncEx | None = None,
+    response_model_exclude: IncEx | None = None,
+    response_model_by_alias: bool = True,
+    response_model_exclude_unset: bool = False,
+    response_model_exclude_defaults: bool = False,
+    response_model_exclude_none: bool = False,
+    include_in_schema: bool = True,
+    response_class: type[Response] = Default(JSONResponse),
+    name: str | None = None,
+    openapi_extra: dict[str, Any] | None = None,
+) -> Callable[[Callable], Callable]:
+    def wrapper(route_handler: Callable) -> Callable:
+        setattr(
+            route_handler,
+            ROUTE_HANDLER_ATTRIBUTE,
+            RouteHandlerMeta(
+                method=HTTPMethods.OPTIONS,
+                path=path,
+                response_model=response_model,
+                status_code=status_code,
+                tags=tags,
+                dependencies=dependencies,
+                summary=summary,
+                description=description,
+                response_description=response_description,
+                responses=responses,
+                deprecated=deprecated,
+                response_model_include=response_model_include,
+                response_model_exclude=response_model_exclude,
+                response_model_by_alias=response_model_by_alias,
+                response_model_exclude_unset=response_model_exclude_unset,
+                response_model_exclude_defaults=response_model_exclude_defaults,
+                response_model_exclude_none=response_model_exclude_none,
+                include_in_schema=include_in_schema,
+                response_class=response_class,
+                name=name,
+                openapi_extra=openapi_extra,
+            ),
+        )
+
+        return route_handler
+
+    return wrapper
+
+
+def head(
+    path: str | None = None,
+    *,
+    response_model: Any | None = Default(None),
+    status_code: int | None = None,
+    tags: list[str | Enum] | None = None,
+    dependencies: Sequence[Depends] | None = None,
+    summary: str | None = None,
+    description: str | None = None,
+    response_description: str = "Successful Response",
+    responses: dict[int | str, dict[str, Any]] | None = None,
+    deprecated: bool | None = None,
+    response_model_include: IncEx | None = None,
+    response_model_exclude: IncEx | None = None,
+    response_model_by_alias: bool = True,
+    response_model_exclude_unset: bool = False,
+    response_model_exclude_defaults: bool = False,
+    response_model_exclude_none: bool = False,
+    include_in_schema: bool = True,
+    response_class: type[Response] = Default(JSONResponse),
+    name: str | None = None,
+    openapi_extra: dict[str, Any] | None = None,
+) -> Callable[[Callable], Callable]:
+    def wrapper(route_handler: Callable) -> Callable:
+        setattr(
+            route_handler,
+            ROUTE_HANDLER_ATTRIBUTE,
+            RouteHandlerMeta(
+                method=HTTPMethods.HEAD,
+                path=path,
+                response_model=response_model,
+                status_code=status_code,
+                tags=tags,
+                dependencies=dependencies,
+                summary=summary,
+                description=description,
+                response_description=response_description,
+                responses=responses,
+                deprecated=deprecated,
+                response_model_include=response_model_include,
+                response_model_exclude=response_model_exclude,
+                response_model_by_alias=response_model_by_alias,
+                response_model_exclude_unset=response_model_exclude_unset,
+                response_model_exclude_defaults=response_model_exclude_defaults,
+                response_model_exclude_none=response_model_exclude_none,
+                include_in_schema=include_in_schema,
+                response_class=response_class,
+                name=name,
+                openapi_extra=openapi_extra,
+            ),
+        )
+
+        return route_handler
+
+    return wrapper
+
+
+def patch(
+    path: str | None = None,
+    *,
+    response_model: Any | None = Default(None),
+    status_code: int | None = None,
+    tags: list[str | Enum] | None = None,
+    dependencies: Sequence[Depends] | None = None,
+    summary: str | None = None,
+    description: str | None = None,
+    response_description: str = "Successful Response",
+    responses: dict[int | str, dict[str, Any]] | None = None,
+    deprecated: bool | None = None,
+    response_model_include: IncEx | None = None,
+    response_model_exclude: IncEx | None = None,
+    response_model_by_alias: bool = True,
+    response_model_exclude_unset: bool = False,
+    response_model_exclude_defaults: bool = False,
+    response_model_exclude_none: bool = False,
+    include_in_schema: bool = True,
+    response_class: type[Response] = Default(JSONResponse),
+    name: str | None = None,
+    openapi_extra: dict[str, Any] | None = None,
+) -> Callable[[Callable], Callable]:
+    def wrapper(route_handler: Callable) -> Callable:
+        setattr(
+            route_handler,
+            ROUTE_HANDLER_ATTRIBUTE,
+            RouteHandlerMeta(
+                method=HTTPMethods.PATCH,
+                path=path,
+                response_model=response_model,
+                status_code=status_code,
+                tags=tags,
+                dependencies=dependencies,
+                summary=summary,
+                description=description,
+                response_description=response_description,
+                responses=responses,
+                deprecated=deprecated,
+                response_model_include=response_model_include,
+                response_model_exclude=response_model_exclude,
+                response_model_by_alias=response_model_by_alias,
+                response_model_exclude_unset=response_model_exclude_unset,
+                response_model_exclude_defaults=response_model_exclude_defaults,
+                response_model_exclude_none=response_model_exclude_none,
+                include_in_schema=include_in_schema,
+                response_class=response_class,
+                name=name,
+                openapi_extra=openapi_extra,
+            ),
+        )
+
+        return route_handler
+
+    return wrapper
+
+
+def trace(
+    path: str | None = None,
+    *,
+    response_model: Any | None = Default(None),
+    status_code: int | None = None,
+    tags: list[str | Enum] | None = None,
+    dependencies: Sequence[Depends] | None = None,
+    summary: str | None = None,
+    description: str | None = None,
+    response_description: str = "Successful Response",
+    responses: dict[int | str, dict[str, Any]] | None = None,
+    deprecated: bool | None = None,
+    response_model_include: IncEx | None = None,
+    response_model_exclude: IncEx | None = None,
+    response_model_by_alias: bool = True,
+    response_model_exclude_unset: bool = False,
+    response_model_exclude_defaults: bool = False,
+    response_model_exclude_none: bool = False,
+    include_in_schema: bool = True,
+    response_class: type[Response] = Default(JSONResponse),
+    name: str | None = None,
+    openapi_extra: dict[str, Any] | None = None,
+) -> Callable[[Callable], Callable]:
+    def wrapper(route_handler: Callable) -> Callable:
+        setattr(
+            route_handler,
+            ROUTE_HANDLER_ATTRIBUTE,
+            RouteHandlerMeta(
+                method=HTTPMethods.TRACE,
+                path=path,
+                response_model=response_model,
+                status_code=status_code,
+                tags=tags,
+                dependencies=dependencies,
+                summary=summary,
+                description=description,
+                response_description=response_description,
+                responses=responses,
+                deprecated=deprecated,
+                response_model_include=response_model_include,
+                response_model_exclude=response_model_exclude,
+                response_model_by_alias=response_model_by_alias,
+                response_model_exclude_unset=response_model_exclude_unset,
+                response_model_exclude_defaults=response_model_exclude_defaults,
+                response_model_exclude_none=response_model_exclude_none,
+                include_in_schema=include_in_schema,
+                response_class=response_class,
+                name=name,
+                openapi_extra=openapi_extra,
+            ),
+        )
+
+        return route_handler
+
+    return wrapper
+
+
+class ControllerBase:
+    def get_api_router(self) -> APIRouter:
+        api_router = getattr(self, API_CONTROLLER_ATTRIBUTE, None)
+
+        if api_router is None:
+            raise AttributeError(
+                f"{self.__class__.__name__} not a api controller, possibly no annotated with either `ApiController`"
+            )
+
+        return api_router
+
+    def register_route_handlers(self) -> APIRouter:
+        api_router = self.get_api_router()
+
+        for attribute_name in dir(self):
+            attribute = getattr(self, attribute_name, None)
+
+            if attribute is None:
+                continue
+
+            route_handler_meta = getattr(
+                attribute, ROUTE_HANDLER_ATTRIBUTE, None
+            )
+
+            if route_handler_meta is None:
+                continue
+
+            if not isinstance(route_handler_meta, RouteHandlerMeta):
+                raise TypeError(
+                    f"expected `{ROUTE_HANDLER_ATTRIBUTE}` to be of type `RouteHandlerMeta`, got {type(route_handler_meta)}"
+                )
+
+            api_router_method = None
+
+            match route_handler_meta.method:
+                case HTTPMethods.GET:
+                    api_router_method = api_router.get
+                case HTTPMethods.PUT:
+                    api_router_method = api_router.put
+                case HTTPMethods.POST:
+                    api_router_method = api_router.post
+                case HTTPMethods.DELETE:
+                    api_router_method = api_router.delete
+                case HTTPMethods.OPTIONS:
+                    api_router_method = api_router.options
+                case HTTPMethods.HEAD:
+                    api_router_method = api_router.head
+                case HTTPMethods.PATCH:
+                    api_router_method = api_router.patch
+                case HTTPMethods.TRACE:
+                    api_router_method = api_router.trace
+
+            if api_router_method is None:
+                raise ValueError(
+                    f"api router method {route_handler_meta.method} not supported"
+                )
+
+            api_router_method(
+                path=route_handler_meta.path or "",
+                response_model=route_handler_meta.response_model,
+                status_code=route_handler_meta.status_code,
+                tags=route_handler_meta.tags,
+                dependencies=route_handler_meta.dependencies,
+                summary=route_handler_meta.summary,
+                description=route_handler_meta.description,
+                response_description=route_handler_meta.response_description,
+                responses=route_handler_meta.responses,
+                deprecated=route_handler_meta.deprecated,
+                response_model_include=route_handler_meta.response_model_include,
+                response_model_exclude=route_handler_meta.response_model_exclude,
+                response_model_by_alias=route_handler_meta.response_model_by_alias,
+                response_model_exclude_unset=route_handler_meta.response_model_exclude_unset,
+                response_model_exclude_defaults=route_handler_meta.response_model_exclude_defaults,
+                response_model_exclude_none=route_handler_meta.response_model_exclude_none,
+                include_in_schema=route_handler_meta.include_in_schema,
+                response_class=route_handler_meta.response_class,
+                name=route_handler_meta.name,
+                openapi_extra=route_handler_meta.openapi_extra,
+            )(attribute)
+
+        return api_router

qena_shared_lib/logging.py

@@ -0,0 +1,63 @@
+from functools import lru_cache
+from logging import (
+    INFO,
+    Formatter,
+    Handler,
+    Logger,
+    StreamHandler,
+    getLogger,
+)
+from os import environ
+from typing import Optional
+
+__all__ = [
+    "LoggerProvider",
+]
+
+ROOT_LOGGER_NAME = environ.get("LOGGER_NAME") or "qena_shared_lib"
+
+
+class LoggerProvider:
+    def __init__(self):
+        logger = self.get_logger()
+
+        logger.setLevel(INFO)
+
+    @lru_cache
+    @staticmethod
+    def default() -> "LoggerProvider":
+        return LoggerProvider()
+
+    @lru_cache
+    def get_logger(self, name: str | None = None) -> Logger:
+        logger_name = ROOT_LOGGER_NAME
+
+        if name:
+            logger_name = f"{ROOT_LOGGER_NAME}.{name.strip('.')}"
+
+        logger = getLogger(logger_name)
+        handlers = [handler.__class__ for handler in logger.handlers]
+
+        if logger.parent is not None:
+            self._check_handler(handlers=handlers, logger=logger.parent)
+
+        if StreamHandler not in handlers:
+            stream_handler = StreamHandler()
+
+            stream_handler.setFormatter(
+                Formatter(
+                    "[ %(levelname)-8s] %(name)s [ %(filename)s:%(lineno)d in %(funcName)s ]  ---  %(message)s"
+                )
+            )
+            logger.addHandler(stream_handler)
+
+        return logger
+
+    def _check_handler(
+        self, handlers: list[type[Handler]], logger: Optional[Logger] = None
+    ):
+        if logger is None:
+            return handlers
+
+        handlers.extend([handler.__class__ for handler in logger.handlers])
+        self._check_handler(handlers=handlers, logger=logger.parent)