algo-backend-framework 0.0.1__py3-none-any.whl

algo_backend/starter/default_app_generator.py

@@ -0,0 +1,169 @@
+import logging
+from contextlib import asynccontextmanager
+from typing import Any, Callable, Coroutine, Dict, List, Optional
+
+from fastapi import FastAPI
+from fastapi.exceptions import RequestValidationError, StarletteHTTPException
+from starlette.middleware import Middleware
+
+from algo_backend.exception import ApiErrorCodeManage
+from algo_backend.intercept import (
+    BasicExceptionInterceptor,
+    HTTPExceptionInterceptor,
+    ValidateExceptionInterceptor,
+)
+from algo_backend.log import BasicLogStarter
+from algo_backend.metrics import (
+    PrometheusContext,
+    PrometheusTimeCostMetricSetting,
+)
+from algo_backend.metrics.collector import MetricsScheduleMonitor
+from algo_backend.middleware import default_cors_middleware
+
+from .event_list import EventList
+
+logger = logging.getLogger(__name__)
+
+
+class DefaultAlgoAppGenerator:
+    """
+    FastApi的App初始化，作用于每个fastapi的worker
+    """
+
+    def __init__(
+        self,
+        *,
+        service_name: str,
+        app_error_code_prefix: Optional[int] = None,
+        custom_start_event: List[Callable[[], Coroutine[Any, Any, None]]] = None,
+        custom_end_event: List[Callable[[], Coroutine[Any, Any, None]]] = None,
+        log_starter: Optional[BasicLogStarter] = None,
+        intercept_dict: Optional[Dict[Exception, BasicExceptionInterceptor]] = None,
+        middlewares: List[Middleware] = (default_cors_middleware,),
+        api_time_cost_buckets: Optional[List[int]] = None,
+        client_time_cost_buckets: Optional[List[int]] = None,
+    ):
+        """
+        :param service_name: 服务名称，必填
+        :param app_error_code_prefix: 错误码前缀，两位数字，如果指定则错误码为8位，如果不填则错误码是6位
+        :param custom_start_event: 用户自定义的app时的触发事件列表
+        :param custom_end_event: 用户自定义的app结束的触发事件列表
+        :param log_starter: 日志启动器
+        :param intercept_dict: 拦截器字典，key为异常类型，value为拦截器实例
+        :param middlewares: 中间件列表
+        :param api_time_cost_buckets: 接口耗时统计的桶,None表示使用默认的,空列表表示不启用这个指标
+        :param client_time_cost_buckets: 客户端耗时统计的桶,None表示使用默认的,空列表表示不启用这个指标
+        """
+        # 注册8位错误码前缀
+        ApiErrorCodeManage.set_error_code_prefix_env(app_error_code_prefix)
+        self.service_name = service_name
+
+        self.__app: Optional[FastAPI] = FastAPI()
+
+        self.start_event_list = EventList()
+        self.end_event_list = EventList()
+
+        self.log_starter = log_starter or BasicLogStarter(service_name=service_name)
+
+        self.intercept_dict = {
+            RequestValidationError: ValidateExceptionInterceptor(),
+            StarletteHTTPException: HTTPExceptionInterceptor(),
+        }
+        self.intercept_dict.update(intercept_dict or {})
+
+        self.middleware_list = list(middlewares)
+
+        self.time_cost_metrics_initializer = (
+            lambda: PrometheusTimeCostMetricSetting.initialize(
+                api_metrics_buckets=api_time_cost_buckets,
+                client_metrics_buckets=client_time_cost_buckets,
+            )
+        )
+
+        self.init_start_event(custom_start_event)
+        self.init_end_event(custom_end_event)
+
+    def init_start_event(self, custom_event):
+        """
+        初始化开始事件
+        """
+        self.start_event_list.add(self.log_starter.setup_log())
+        # 启动系统指标、gc指标的定时采集写入以供多进程时的汇总
+        self.start_event_list.add(MetricsScheduleMonitor().run_monitor)
+        # 接口计时器和客户端解释器的初始化
+        self.start_event_list.add(self.time_cost_metrics_initializer)
+        # 插入自定义的开始事件
+        for event in custom_event or []:
+            self.start_event_list.add(event)
+
+    def init_end_event(self, custom_event):
+        """
+        初始化结束事件
+        """
+        # 插入自定义事件
+        for event in custom_event or []:
+            self.end_event_list.add(event)
+
+    def add_middleware(self, middleware: Middleware) -> "DefaultAlgoAppGenerator":
+        """
+        添加中间件
+        """
+        self.middleware_list.append(middleware)
+        return self
+
+    def set_log_stater(self, log_starter: BasicLogStarter) -> "DefaultAlgoAppGenerator":
+        self.log_starter = log_starter
+        return self
+
+    def use_log_loguru(self):
+        """
+        使用loguru日志框架
+        """
+        from algo_backend.log.loguru import LoguruStarter
+
+        return self.set_log_stater(LoguruStarter(service_name=self.service_name))
+
+    def use_log_nblog(self):
+        """
+        使用nblog日志框架，待实现
+        """
+        ...
+
+    def generate(self):
+        self.init_app().add_prometheus_endpoint().add_interceptor()
+        return self.app
+
+    @property
+    def app(self):
+        return self.__app
+
+    def init_app(self, **kwargs):
+        self.__app = FastAPI(
+            lifespan=self.gen_life_span(), middleware=self.middleware_list, **kwargs
+        )
+        return self
+
+    def add_prometheus_endpoint(self):
+        PrometheusContext.mount_prometheus_endpoint(self.__app)
+        return self
+
+    def add_interceptor(self):
+        for exc, interceptor in self.intercept_dict.items():
+            self.__app.add_exception_handler(exc, interceptor.intercept)
+        return self
+
+    def gen_life_span(self):
+        @asynccontextmanager
+        async def lifespan(app: FastAPI):
+            logger.info("ExecuteStartEvent")
+            await self.start_event_list.execute()
+            logger.info("Start App")
+
+            yield
+
+            logger.info("ExecuteStopEvent")
+            await self.end_event_list.execute()
+
+            logger.info("Goodbye")
+
+        return lifespan

algo_backend/starter/default_service_starter.py

@@ -0,0 +1,70 @@
+from typing import Any, Callable, List
+
+import uvicorn
+
+from algo_backend.config import ServiceConfig
+from algo_backend.metrics import PrometheusContext
+
+
+class DefaultAlgoServiceStarter:
+    """
+    主线程的设置
+    uvicorn容器启动fastapi
+    """
+
+    def __init__(self, service_name: str):
+        self.service_name = service_name
+        self.__main_pid_event: List[Callable[[], Any]] = []
+        self.init_events()
+
+    def init_events(self):
+        # 初始化prometheus多进程的设置
+        self.append_event(PrometheusContext.init)
+        return self
+
+    def append_event(self, func: Callable[[], Any]):
+        """尾部插入事件"""
+        self.__main_pid_event.append(func)
+        return self
+
+    def insert_event(self, func: Callable[[], Any], index: int = 0):
+        """任意位置插入事件"""
+        self.__main_pid_event.insert(index, func)
+        return self
+
+    def use_loguru(self):
+        """
+        使用loguru日志设置，对主进程的日志生效
+        注册loguru的定时清理器
+        """
+        from algo_backend.log.loguru import LoguruStarter
+
+        loguru_stater = LoguruStarter(service_name=self.service_name)
+        self.insert_event(loguru_stater.setup_log)
+        self.append_event(loguru_stater.run_log_cleaner)
+        return self
+
+    def main_pid_setup(self) -> "DefaultAlgoServiceStarter":
+        """
+        主进程中的设置事件
+        """
+        for func in self.__main_pid_event:
+            func()
+        return self
+
+    @classmethod
+    def run(
+        cls,
+        app_str: str = "app.backend.application:app",
+        host: str = "0.0.0.0",
+        **kwargs,
+    ):
+        # 启动服务
+        uvicorn.run(
+            app_str,
+            host=host,
+            port=ServiceConfig.HTTP_PORT,
+            timeout_keep_alive=ServiceConfig.TIMEOUT_KEEP_ALIVE,
+            workers=ServiceConfig.PROCESS_NUM,
+            **kwargs,
+        )

algo_backend/starter/event_list.py

@@ -0,0 +1,32 @@
+import asyncio
+from typing import Any, Callable, Coroutine, List, Optional, Union
+
+
+class EventList:
+    def __init__(self):
+        """
+        普通函数和协程函数列表
+        """
+        self.__events: List[
+            Union[Callable, Callable[[], Coroutine[Any, Any, None]]]
+        ] = []
+
+    def add(
+        self,
+        event: Optional[
+            Union[Callable, Callable[[], Coroutine[Any, Any, None]]]
+        ] = None,
+    ):
+        """添加事件到列表"""
+        if event:
+            self.__events.append(event)
+            return self
+
+    async def execute(self):
+        """执行所有事件"""
+
+        for event in self.__events:
+            if asyncio.iscoroutinefunction(event):
+                await event()
+            else:
+                event()

algo_backend/utils/__init__.py

@@ -0,0 +1,8 @@
+from .meta_class import ConstantClass, OsAttrMeta
+from .utils import get_request_id
+
+__all__ = [
+    "get_request_id",
+    "OsAttrMeta",
+    "ConstantClass",
+]

algo_backend/utils/meta_class.py

@@ -0,0 +1,50 @@
+import os
+
+
+class ConstantClassMeta(type):
+    """
+    对子类也生效的元类
+    """
+
+    def __setattr__(cls, name, value):
+        # 检查属性是否已存在且非特殊属性
+        if hasattr(cls, name) and not name.startswith("__"):
+            raise AttributeError(
+                f"The property '{name}' of the constant class {cls.__name__} is not allowed to be modified."
+            )
+
+    def __call__(cls, *args, **kwargs):
+        raise TypeError(f"The constant class {cls.__name__} cannot be instantiated.")
+
+
+class ConstantClass(metaclass=ConstantClassMeta):
+    pass
+
+
+class OsAttrMeta(type(ConstantClass), type):
+    def __new__(cls, name, bases, attrs):
+        for attr in attrs["__annotations__"]:
+            raw_value = os.getenv(attr.upper(), attrs.get(attr, None))
+            expected_type = attrs["__annotations__"][attr]
+
+            # 根据类型提示转换值
+            if expected_type is bool and isinstance(raw_value, str):
+                # 将 "false" 转换为 False，"true" 转换为 True
+                raw_value = raw_value.lower()
+                if raw_value == "true":
+                    raw_value = True
+                elif raw_value == "false":
+                    raw_value = False
+                else:
+                    raise ValueError(
+                        f"Invalid value for boolean attribute '{attr}': {raw_value}"
+                    )
+            elif expected_type is int:
+                raw_value = int(raw_value)
+            elif expected_type is float:
+                raw_value = float(raw_value)
+
+            # 如果环境变量不存在，则保持默认值（如果存在）
+            attrs[attr] = raw_value if raw_value is not None else attrs.get(attr)
+
+        return super().__new__(cls, name, bases, attrs)

algo_backend/utils/utils.py

@@ -0,0 +1,22 @@
+import uuid
+
+from fastapi import Header
+
+
+def gen_random_request_id():
+    return str(uuid.uuid4())
+
+
+async def get_request_id(
+    x_request_id: str = Header(gen_random_request_id(), alias="x-request-id"),
+):
+    """
+    使用示例
+
+    @app.post("/example/help")
+    async def run(body: Body, reqid=Depends(get_request_id)):
+        ...
+
+    如果请求头中没有x-request-id，则会触发validate_interceptor的检验
+    """
+    return x_request_id

algo_backend_framework-0.0.1.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: algo-backend-framework
+Version: 0.0.1
+Summary: Ctcdn algorithm backend framework
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.128.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: prometheus-client>=0.24.1
+Requires-Dist: psutil>=7.2.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: uvicorn>=0.40.0
+
+# algo-backend-framework-python
+
+# 功能概述
+- 配置
+- 错误码、异常、参数检验报错转换
+- 标准响应体、x-request-id
+- 日志框架支持：loguru、nb_log
+- 多进程prometheus指标
+- otel
+
+## 分支规范
+- master分支: 归档分支
+- release/release-×.×.×: 发布分支，×.×.×为版本号；修改[pyproject.toml](pyproject.toml)中的version构建并发布包
+- dev分支: 开发分支；合并至release分支时，需要提mr，mr需要填写版本号和功能描述；需要充分自测和review之后才能合并至release
+- feat/feat-×××××: 功能分支；合并至dev时需要mr，mr需要填写功能名称和功能描述；新功能或较大重构需要建feat分支，较小的改动不必开feat分支
+
+## 本地调试
+
+本地开发需要打包验证，则先构建包（但不要发布），然后在本地目录离线安装
+```shell
+# 构建包
+uv build
+# 拷贝wheel包到本地测试目录下执行以下命令
+uv add algo_backend_framework-*.*.*-py3-none-any.whl
+# 调试时发现包有问题，只需要remove后重新打包，并重新add
+uv remove algo-backend-framework
+```
+
+## 开发约定
+- 代码提交前进行sonar扫描和语法检查，并进行代码格式化
+    ```
+    uv run ruff format algo_backend/×××××
+    ```
+- 子模块__init__.py文件需要声明包内暴露模块，不建议用户通过包内文件名导入，以减少后期微调重构引起的不兼容
+- 跨模块导入一律使用`from algo_backend.× import 模块名`的全限定包名，同级目录下导入从使用`from . import `
+
+
+## 发布
+- 在release分支进行构建和推送
+```shell
+uv build
+# 推送ctcdn nexus
+uv publish --index ctcdn-pypi-upload
+# 推送pypi
+uv publish
+```

algo_backend_framework-0.0.1.dist-info/RECORD

@@ -0,0 +1,48 @@
+algo_backend/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+algo_backend/config/__init__.py,sha256=MLAvcvodxXiaVsSJaVvQcNjFWIFusBQ0i9OrWJv3zv0,222
+algo_backend/config/basic_config.py,sha256=RSRf8lgc8KfA_FHNjchaghSLNnJy7ejn2ux57SBSakg,292
+algo_backend/config/loguru_config.py,sha256=WovghKcMqeysPuf8vlKFhbNug8Z7zPqxkjlwVYKjZWw,513
+algo_backend/exception/__init__.py,sha256=yYGpAk5oMGDsXDQwjcVMZJT1irwtG0oQacSrv1_VrFo,580
+algo_backend/exception/error_code_manage.py,sha256=d29aMgelf93RUqlvLTjQDxBiSH9ZVFYbW66rzTWDKM4,4391
+algo_backend/exception/exception.py,sha256=Y5YX45nT3tbZ2uBwraTXBqXlpWjpz9fQ0ICfIM3M4kM,1205
+algo_backend/exception/status_code.py,sha256=s5lXXR-oSALk3gtI4KcPKHstvnRFArQL1SEgQFIeSxU,2707
+algo_backend/handler/__init__.py,sha256=hyZWIopKZZX5eoGGmqkepjcF2Vfy6oSFAc2NRlVHOQI,107
+algo_backend/handler/exception_to_vo.py,sha256=e1jM9YvoTEmWL73I5uV_F1xo9UA7LgnWYfFdI7wFidA,1005
+algo_backend/handler/operation_handler.py,sha256=7ffsgjj1EZ_d3x_jx9krju_uwCmwfjXHJ_9KZ8SrpOw,2654
+algo_backend/intercept/__init__.py,sha256=FoNHCzUc3ceLo85ECN3L7HzW6KmLqcG5sgMh_qULLdw,265
+algo_backend/intercept/common.py,sha256=T50_IAeY0HQ8TbupjYvMHMObg3j9I4lQnqZMiWNzuQw,1445
+algo_backend/intercept/http.py,sha256=C_N2nyErFhdOZ1LPQ6iU_JCy4fFYEucDwhWJb-qBnbc,1381
+algo_backend/intercept/validate.py,sha256=FBaLc2CRxtIjfjudOH41nwAX7jKXlWJHgUFooC19deI,2949
+algo_backend/log/__init__.py,sha256=0bRk_Y5olw95oIR7DabfT-1gJv_WdXhe7ToufAr5VKo,36
+algo_backend/log/common.py,sha256=1h9zuCuoas3qUr9yG2fvm_3WNYVQW2eH5DJzS0IMvFQ,355
+algo_backend/log/loguru/__init__.py,sha256=zOfdTmDUf6bFeZeZYbXEg1EMMm3ju90k5dtdpN7Sn0s,177
+algo_backend/log/loguru/log_clean.py,sha256=_BVF9dLooTGIgwctjuqba6hEUUvHww8JuUzFHO88GEM,4590
+algo_backend/log/loguru/log_setup.py,sha256=Xnw6JCB8gBfm6z-KxTSdenoxfsxwiZGWOs75DpE0N3w,3010
+algo_backend/log/loguru/log_starter.py,sha256=2YsLrdNPlF0Mgu4hduEYJGidLtnkFgtoMlzEzOJyuUc,1841
+algo_backend/log/loguru/patch_logging.py,sha256=GS8x0MmIjqaY5nmiPgjU01yNG1AvbOrTU8xKzwb2Vdc,2796
+algo_backend/log/nblog/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+algo_backend/metrics/__init__.py,sha256=20CPEFgi0yJ2Fy-LTcFQ3aqlXHhLPtgPFboqOMBhl34,640
+algo_backend/metrics/http_metrics.py,sha256=3GYNhKJoS6oJ8L7FXnVkPZ_wa-SKj_444KLdBeGkbs4,1944
+algo_backend/metrics/prometheus_context.py,sha256=GqemLccNbTx_5DBijOyzySzWydbpWYfnhWh17rujjwE,1910
+algo_backend/metrics/time_cost_metrics.py,sha256=0v8Mu4lXbgKjAFH3aK0GPtVhw_70kIYMd-eH-ceyrkI,4645
+algo_backend/metrics/collector/__init__.py,sha256=t5Csl-Z9qpik-isEUVYDYBWYgf7xdM49548YfJr4X64,413
+algo_backend/metrics/collector/common.py,sha256=yeiZp9ufbYSW7N-R6ytk74UF0dCqJ8r338lL64TmA4g,475
+algo_backend/metrics/collector/gc_metrics.py,sha256=s2ariKimji9LC71eAQFlrFkpcF3hkSy5IBC6D8LFePc,2510
+algo_backend/metrics/collector/schedule_monitor.py,sha256=PTdUIFLrcWFZG5bUlaRj9FJHIy3ulCUk3ExQqVZwRgU,1585
+algo_backend/metrics/collector/system_metrics.py,sha256=SxOswHKGKLDB5wMsKjd7rkQtofhc432OIm4OvlT5ciM,5329
+algo_backend/middleware/__init__.py,sha256=KfSRT3TZ89BzY__Rrbu-9HkjO1LToD5sXyl_J4Po7Q4,173
+algo_backend/middleware/cors.py,sha256=kKdPeZMS38IVvOueJz34lQX1t1hH5OOz068IdIAR-Kc,271
+algo_backend/middleware/metrics.py,sha256=XwZGipQwKp20naZglx41Wc79rXud81Y4AIfswUJj3jM,385
+algo_backend/schema/__init__.py,sha256=STf9SdNuP5dzMDehdGjJGHQ7Pq-qO4jw-5CWsayvx5g,90
+algo_backend/schema/vo.py,sha256=CSYNHpJx2YNCZ5-4GjjSs6BNKiJEyl31gnplnxGvXfY,2211
+algo_backend/starter/__init__.py,sha256=2AfidtR7PmlhVPz65tt_t3QdIYqpp0mVg8M-lbJE2F4,194
+algo_backend/starter/default_app_generator.py,sha256=kUANISNpGHafJPVgTOG-BrcQNRUOn31tSv38tTun9qc,6094
+algo_backend/starter/default_service_starter.py,sha256=QHVDAS4css7tYCH7Fd_is2uWX8fxV1GD7LAugx904B8,2017
+algo_backend/starter/event_list.py,sha256=vQHzQIpW8LZmQ93YyET-1gX6pQGVE5A6I_pLoYTFOH0,824
+algo_backend/utils/__init__.py,sha256=oX6OyL-28jzc94u4fyH1TtntCzQySkfZ8jibMk1KPU8,168
+algo_backend/utils/meta_class.py,sha256=hcZPGF7EIHvJOXXR82_7Gah_AWbqkcSxUc473I_6maY,1850
+algo_backend/utils/utils.py,sha256=q3bxBrivndLRggWsLryloSpu-_Ecbj4mhZL8oYdiDTo,481
+algo_backend_framework-0.0.1.dist-info/METADATA,sha256=D4eriT_lp8IIMOwz5JLKBGca-6k7STDRBNKTLcmMVRE,2196
+algo_backend_framework-0.0.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+algo_backend_framework-0.0.1.dist-info/top_level.txt,sha256=zLsbLTRV1tO2hQfazqiBLO73VnjSAhJSUpMMBmQaLfw,13
+algo_backend_framework-0.0.1.dist-info/RECORD,,

algo_backend_framework-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

algo_backend_framework-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+algo_backend