shaapi 0.1.0__py3-none-any.whl

shaapi/template/backend/common/exception/exception_handler.py

@@ -0,0 +1,280 @@
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from pydantic import ValidationError
+from pydantic.errors import PydanticUserError
+from starlette.exceptions import HTTPException
+from starlette.middleware.cors import CORSMiddleware
+from uvicorn.protocols.http.h11_impl import STATUS_PHRASES
+
+from backend.common.exception.errors import BaseExceptionMixin
+from backend.common.response.response_code import CustomResponseCode, StandardResponseCode
+from backend.common.response.response_schema import response_base
+from backend.common.schema import (
+    CUSTOM_USAGE_ERROR_MESSAGES,
+    CUSTOM_VALIDATION_ERROR_MESSAGES,
+)
+from backend.core.conf import settings
+from backend.utils.serializers import MsgSpecJSONResponse
+from backend.utils.trace_id import get_request_trace_id
+
+
+def _get_exception_code(status_code: int):
+    """
+    Get return status code, OpenAPI, Uvicorn... The available status codes are based on the RFC definitions, see the link below for detailed code.
+
+    `python Status Code Standard Support <https://github.com/python/cpython/blob/6e3cc72afeaee2532b4327776501eb8234ac787b/Lib/http
+    /__init__.py#L7>`__
+
+    `IANA status code registry <https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml>`__
+
+    :param status_code:
+    :return:
+    """
+    try:
+        STATUS_PHRASES[status_code]
+    except Exception:
+        code = StandardResponseCode.HTTP_400
+    else:
+        code = status_code
+    return code
+
+
+async def _validation_exception_handler(request: Request, e: RequestValidationError | ValidationError):
+    """
+    Data Validation Exception Handling
+
+    :param e:
+    :return:
+    """
+    errors = []
+    for error in e.errors():
+        custom_message = CUSTOM_VALIDATION_ERROR_MESSAGES.get(error['type'])
+        if custom_message:
+            ctx = error.get('ctx')
+            if not ctx:
+                error['msg'] = custom_message
+            else:
+                error['msg'] = custom_message.format(**ctx)
+                ctx_error = ctx.get('error')
+                if ctx_error:
+                    error['ctx']['error'] = (
+                        ctx_error.__str__().replace("'", '"') if isinstance(ctx_error, Exception) else None
+                    )
+        errors.append(error)
+    error = errors[0]
+    if error.get('type') == 'json_invalid':
+        message = 'json parsing failure'
+    else:
+        error_input = error.get('input')
+        field = str(error.get('loc')[-1])
+        error_msg = error.get('msg')
+        message = f'{field} {error_msg} Input:{error_input}' if settings.ENVIRONMENT == 'dev' else error_msg
+    msg = f'Illegal request parameters: {message}'
+    data = {'errors': errors} if settings.ENVIRONMENT == 'dev' else None
+    content = {
+        'code': StandardResponseCode.HTTP_422,
+        'msg': msg,
+        'data': data,
+    }
+    request.state.__request_validation_exception__ = content  # 用于在中间件中获取异常信息
+    content.update(trace_id=get_request_trace_id(request))
+    return MsgSpecJSONResponse(status_code=422, content=content)
+
+
+def register_exception(app: FastAPI):
+    @app.exception_handler(HTTPException)
+    async def http_exception_handler(request: Request, exc: HTTPException):
+        """
+        Global HTTP Exception Handling
+
+        :param request:
+        :param exc:
+        :return:
+        """
+        if settings.ENVIRONMENT == 'dev':
+            content = {
+                'code': exc.status_code,
+                'msg': exc.detail,
+                'data': None,
+            }
+        else:
+            res = response_base.fail(request=request, res=CustomResponseCode.HTTP_400)
+            content = res.model_dump()
+        request.state.__request_http_exception__ = content
+        content.update(trace_id=get_request_trace_id(request))
+        return MsgSpecJSONResponse(
+            status_code=_get_exception_code(exc.status_code),
+            content=content,
+            headers=exc.headers,
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def fastapi_validation_exception_handler(request: Request, exc: RequestValidationError):
+        """
+        fastapi Data Validation Exception Handling
+
+        :param request:
+        :param exc:
+        :return:
+        """
+        return await _validation_exception_handler(request, exc)
+
+    @app.exception_handler(ValidationError)
+    async def pydantic_validation_exception_handler(request: Request, exc: ValidationError):
+        """
+        pydantic Data Validation Exception Handling
+
+        :param request:
+        :param exc:
+        :return:
+        """
+        return await _validation_exception_handler(request, exc)
+
+    @app.exception_handler(PydanticUserError)
+    async def pydantic_user_error_handler(request: Request, exc: PydanticUserError):
+        """
+        Pydantic User Exception Handling
+
+        :param request:
+        :param exc:
+        :return:
+        """
+        content = {
+            'code': StandardResponseCode.HTTP_500,
+            'msg': CUSTOM_USAGE_ERROR_MESSAGES.get(exc.code),
+            'data': None,
+        }
+        request.state.__request_pydantic_user_error__ = content
+        content.update(trace_id=get_request_trace_id(request))
+        return MsgSpecJSONResponse(
+            status_code=StandardResponseCode.HTTP_500,
+            content=content,
+        )
+
+    @app.exception_handler(AssertionError)
+    async def assertion_error_handler(request: Request, exc: AssertionError):
+        """
+        assertion error handling
+
+        :param request:
+        :param exc:
+        :return:
+        """
+        if settings.ENVIRONMENT == 'dev':
+            content = {
+                'code': StandardResponseCode.HTTP_500,
+                'msg': str(''.join(exc.args) if exc.args else exc.__doc__),
+                'data': None,
+            }
+        else:
+            res = response_base.fail(request=request, res=CustomResponseCode.HTTP_500)
+            content = res.model_dump()
+        request.state.__request_assertion_error__ = content
+        content.update(trace_id=get_request_trace_id(request))
+        return MsgSpecJSONResponse(
+            status_code=StandardResponseCode.HTTP_500,
+            content=content,
+        )
+
+    @app.exception_handler(BaseExceptionMixin)
+    async def custom_exception_handler(request: Request, exc: BaseExceptionMixin):
+        """
+        Global custom exception handling
+
+        :param request:
+        :param exc:
+        :return:
+        """
+        content = {
+            'code': exc.code,
+            'msg': str(exc.msg),
+            'data': exc.data if exc.data else None,
+        }
+        request.state.__request_custom_exception__ = content
+        content.update(trace_id=get_request_trace_id(request))
+        return MsgSpecJSONResponse(
+            status_code=_get_exception_code(exc.code),
+            content=content,
+            background=exc.background,
+        )
+
+    @app.exception_handler(Exception)
+    async def all_unknown_exception_handler(request: Request, exc: Exception):
+        """
+        global unknown exception handling (GUE)
+
+        :param request:
+        :param exc:
+        :return:
+        """
+        if settings.ENVIRONMENT == 'dev':
+            content = {
+                'code': StandardResponseCode.HTTP_500,
+                'msg': str(exc),
+                'data': None,
+            }
+        else:
+            res = response_base.fail(request=request, res=CustomResponseCode.HTTP_500)
+            content = res.model_dump()
+        request.state.__request_all_unknown_exception__ = content
+        content.update(trace_id=get_request_trace_id(request))
+        return MsgSpecJSONResponse(
+            status_code=StandardResponseCode.HTTP_500,
+            content=content,
+        )
+
+    if settings.MIDDLEWARE_CORS:
+
+        @app.exception_handler(StandardResponseCode.HTTP_500)
+        async def cors_custom_code_500_exception_handler(request, exc):
+            """
+            Cross Domain Customization 500 Exception Handling
+
+            `Related issue <https://github.com/encode/starlette/issues/1175>`_
+            `Solution <https://github.com/fastapi/fastapi/discussions/7847#discussioncomment-5144709>`_
+
+            :param request:
+            :param exc:
+            :return:
+            """
+            if isinstance(exc, BaseExceptionMixin):
+                content = {
+                    'code': exc.code,
+                    'msg': exc.msg,
+                    'data': exc.data,
+                }
+            else:
+                if settings.ENVIRONMENT == 'dev':
+                    content = {
+                        'code': StandardResponseCode.HTTP_500,
+                        'msg': str(exc),
+                        'data': None,
+                    }
+                else:
+                    res = response_base.fail(request=request, res=CustomResponseCode.HTTP_500)
+                    content = res.model_dump()
+            request.state.__request_cors_500_exception__ = content
+            content.update(trace_id=get_request_trace_id(request))
+            response = MsgSpecJSONResponse(
+                status_code=exc.code if isinstance(exc, BaseExceptionMixin) else StandardResponseCode.HTTP_500,
+                content=content,
+                background=exc.background if isinstance(exc, BaseExceptionMixin) else None,
+            )
+            origin = request.headers.get('origin')
+            if origin:
+                cors = CORSMiddleware(
+                    app=app,
+                    allow_origins=settings.CORS_ALLOWED_ORIGINS,
+                    allow_credentials=True,
+                    allow_methods=['*'],
+                    allow_headers=['*'],
+                    expose_headers=settings.CORS_EXPOSE_HEADERS,
+                )
+                response.headers.update(cors.simple_headers)
+                has_cookie = 'cookie' in request.headers
+                if cors.allow_all_origins and has_cookie:
+                    response.headers['Access-Control-Allow-Origin'] = origin
+                elif not cors.allow_all_origins and cors.is_allowed_origin(origin=origin):
+                    response.headers['Access-Control-Allow-Origin'] = origin
+                    response.headers.add_vary_header('Origin')
+            return response

shaapi/template/backend/common/log.py

@@ -0,0 +1,123 @@
+import inspect
+import logging
+import os
+
+from sys import stderr, stdout
+
+from asgi_correlation_id import correlation_id
+from loguru import logger
+
+from backend.core import path_conf
+from backend.core.conf import settings
+
+
+class InterceptHandler(logging.Handler):
+    """
+    Default handler from examples in loguru documentation.
+    See https://loguru.readthedocs.io/en/stable/overview.html#entirely-compatible-with-standard-logging
+    """
+
+    def emit(self, record: logging.LogRecord):
+        # Get corresponding Loguru level if it exists
+        try:
+            level = logger.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+
+        # Find caller from where originated the logged message.
+        frame, depth = inspect.currentframe(), 0
+        while frame and (depth == 0 or frame.f_code.co_filename == logging.__file__):
+            frame = frame.f_back
+            depth += 1
+
+        logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())
+
+
+def setup_logging():
+    """
+    From https://pawamoy.github.io/posts/unify-logging-for-a-gunicorn-uvicorn-app/
+    https://github.com/pawamoy/pawamoy.github.io/issues/17
+    """
+    # Intercept everything at the root logger
+    logging.root.handlers = [InterceptHandler()]
+    logging.root.setLevel(settings.LOG_ROOT_LEVEL)
+
+    # Remove all log handlers and propagate to root logger
+    for name in logging.root.manager.loggerDict.keys():
+        logging.getLogger(name).handlers = []
+        if 'uvicorn.access' in name or 'watchfiles.main' in name:
+            logging.getLogger(name).propagate = False
+        else:
+            logging.getLogger(name).propagate = True
+
+        # Debug log handlers
+        # logging.debug(f'{logging.getLogger(name)}, {logging.getLogger(name).propagate}')
+
+    # Remove every other logger's handlers
+    logger.remove()
+
+    # Define the correlation_id filter function
+    # https://github.com/snok/asgi-correlation-id?tab=readme-ov-file#configure-logging
+    # https://github.com/snok/asgi-correlation-id/issues/7
+    def correlation_id_filter(record) -> bool:
+        cid = correlation_id.get(settings.LOG_CID_DEFAULT_VALUE)
+        record['correlation_id'] = cid[: settings.LOG_CID_UUID_LENGTH]
+        return True
+
+    # Configure loguru logger before starts logging
+    logger.configure(
+        handlers=[
+            {
+                'sink': stdout,
+                'level': settings.LOG_STDOUT_LEVEL,
+                'filter': lambda record: correlation_id_filter(record) and record['level'].no <= 25,
+                'format': settings.LOG_STD_FORMAT,
+            },
+            {
+                'sink': stderr,
+                'level': settings.LOG_STDERR_LEVEL,
+                'filter': lambda record: correlation_id_filter(record) and record['level'].no >= 30,
+                'format': settings.LOG_STD_FORMAT,
+            },
+        ]
+    )
+
+
+def set_customize_logfile():
+    log_path = path_conf.LOG_DIR
+    if not os.path.exists(log_path):
+        os.mkdir(log_path)
+
+    # log files
+    log_stdout_file = os.path.join(log_path, settings.LOG_STDOUT_FILENAME)
+    log_stderr_file = os.path.join(log_path, settings.LOG_STDERR_FILENAME)
+
+    # loguru logger: https://loguru.readthedocs.io/en/stable/api/logger.html#loguru._logger.Logger.add
+    log_config = {
+        'rotation': '10 MB',
+        'retention': '15 days',
+        'compression': 'tar.gz',
+        'enqueue': True,
+        'format': settings.LOG_LOGURU_FORMAT,
+    }
+
+    # stdout file
+    logger.add(
+        str(log_stdout_file),
+        level=settings.LOG_STDOUT_LEVEL,
+        **log_config,
+        backtrace=False,
+        diagnose=False,
+    )
+
+    # stderr file
+    logger.add(
+        str(log_stderr_file),
+        level=settings.LOG_STDERR_LEVEL,
+        **log_config,
+        backtrace=True,
+        diagnose=True,
+    )
+
+
+log = logger

shaapi/template/backend/common/model.py

@@ -0,0 +1,68 @@
+from sqlalchemy.orm import DeclarativeBase, Mapped, MappedAsDataclass, declared_attr, mapped_column
+from sqlalchemy import DateTime, func
+from ulid import ULID
+from typing import Annotated
+from datetime import datetime
+from sqlalchemy.sql.functions import current_timestamp
+
+
+
+id_key = Annotated[
+    int, mapped_column(primary_key=True, index=True, autoincrement=True, sort_order=-999, comment='Primary key id')
+]
+
+def get_id() -> str:
+    """Create a new ULID object from the current timestamp"""
+    return str(ULID()).lower()
+
+# Mixin: A concept of object-oriented programming, makes the structure clearer, `Wiki <https://en.wikipedia.org/wiki/Mixin/>`__
+class UserMixin(MappedAsDataclass):
+    """User Mixin data class"""
+
+    create_user: Mapped[int] = mapped_column(sort_order=998, comment='Creator')
+    update_user: Mapped[int | None] = mapped_column(init=False, default=None, sort_order=998, comment='Updater')
+
+
+class DateTimeMixin(MappedAsDataclass):
+    """Datetime Mixin data class"""
+
+    created_time: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), init=False, default=current_timestamp(), comment='Creation time'
+    )
+    updated_time: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), init=False, onupdate=func.now(),  comment='update time'
+    )
+
+
+
+class MappedBase(DeclarativeBase):
+    """
+    Declarative base class, the original DeclarativeBase class, exists as the parent class of all base or data model classes
+
+    `DeclarativeBase <https://docs.sqlalchemy.org/en/20/orm/declarative_config.html>`__
+    `mapped_column() <https://docs.sqlalchemy.org/en/20/orm/mapping_api.html#sqlalchemy.orm.mapped_column>`__
+    """
+
+    @declared_attr.directive
+    def __tablename__(cls) -> str:
+        return cls.__name__.lower()
+
+
+class DataClassBase(MappedAsDataclass, MappedBase):
+    """
+    Declarative data class base, it integrates with the data class, allowing for more advanced configuration, 
+    but you must be aware of some of its features, especially when used together with DeclarativeBase
+
+    `MappedAsDataclass <https://docs.sqlalchemy.org/en/20/orm/dataclasses.html#orm-declarative-native-dataclasses>`__
+    """  # noqa: E501
+
+    __abstract__ = True
+
+
+class Base(DataClassBase, DateTimeMixin):
+    """
+    Declarative Mixin data class base, integrates with the data class, and includes the basic table structure of the Mixin data class. 
+    You can simply understand it as a base class for data classes that includes the basic table structure.
+    """  # noqa: E501
+
+    __abstract__ = True

shaapi/template/backend/common/pagination.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import math
+
+from typing import TYPE_CHECKING, Dict, Generic, Sequence, TypeVar
+
+from fastapi import Depends, Query
+from fastapi_pagination import pagination_ctx
+from fastapi_pagination.bases import AbstractPage, AbstractParams, RawParams
+from fastapi_pagination.ext.sqlalchemy import paginate
+from fastapi_pagination.links.bases import create_links
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from sqlalchemy import Select
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+T = TypeVar('T')
+DataT = TypeVar('DataT')
+SchemaT = TypeVar('SchemaT')
+
+
+class _Params(BaseModel, AbstractParams):
+    page: int = Query(1, ge=1, description='Page number')
+    size: int = Query(10, gt=0, le=100, description='Page size')   # Default 10 records
+
+    def to_raw_params(self) -> RawParams:
+        return RawParams(
+            limit=self.size,
+            offset=self.size * (self.page - 1),
+        )
+
+
+class _Page(AbstractPage[T], Generic[T]):
+    items: Sequence[T]  # Data
+    total: int  # total data
+    page: int  # Page n
+    size: int  # per page
+    total_pages: int  # of total pages
+    links: Dict[str, str | None]  # Jump links
+
+    __params_type__ = _Params  # Use custom Params
+
+    @classmethod
+    def create(
+        cls,
+        items: Sequence[T],
+        total: int,
+        params: _Params,
+    ) -> _Page[T]:
+        page = params.page
+        size = params.size
+        total_pages = math.ceil(total / params.size)
+        links = create_links(**{
+            'first': {'page': 1, 'size': f'{size}'},
+            'last': {'page': f'{math.ceil(total / params.size)}', 'size': f'{size}'} if total > 0 else None,
+            'next': {'page': f'{page + 1}', 'size': f'{size}'} if (page + 1) <= total_pages else None,
+            'prev': {'page': f'{page - 1}', 'size': f'{size}'} if (page - 1) >= 1 else None,
+        }).model_dump()
+
+        return cls(items=items, total=total, page=params.page, size=params.size, total_pages=total_pages, links=links)
+
+
+class _PageData(BaseModel, Generic[DataT]):
+    page_data: DataT | None = None
+
+
+async def paging_data(db: AsyncSession, select: Select, page_data_schema: SchemaT) -> dict:
+    """
+    Creating Paged Data Based on SQLAlchemy
+
+    :param db:
+    :param select:
+    :param page_data_schema:
+    :return:
+    """
+    _paginate = await paginate(db, select)
+    page_data = _PageData[_Page[page_data_schema]](page_data=_paginate).model_dump()['page_data']
+    return page_data
+
+
+# Paging dependency injection
+DependsPagination = Depends(pagination_ctx(_Page))