lumary 0.1.0__tar.gz

lumary-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zarkhan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lumary-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: lumary
+Version: 0.1.0
+Summary: 基于 FastAPI 封装的生产级 Web 应用框架
+Author-email: zarkhan <hanguangzheng@qq.com>
+License: MIT
+Project-URL: Homepage, https://github.com/zarkhan/lumary
+Project-URL: Repository, https://github.com/zarkhan/lumary
+Project-URL: Documentation, https://github.com/zarkhan/lumary#readme
+Keywords: fastapi,web,framework,lumary,async
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.136.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: python-ulid>=3.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == "dev"
+Requires-Dist: asyncpg>=0.29.0; extra == "dev"
+Dynamic: license-file
+
+# Lumary
+
+基于 FastAPI 封装的生产级 Web 应用框架，开箱即用。
+
+## 特性
+
+- **应用封装** — `Lumary` 类继承 FastAPI，内置异常处理、CORS 中间件、自定义 OpenAPI 文档、健康检查
+- **生命周期钩子** — `@on_startup` / `@on_shutdown` 装饰器，支持优先级排序与异常终止控制
+- **统一响应格式** — `APIResponse`、`PageData`、`PageQuery` 等标准化 Schema
+- **业务异常** — `BusinessException` 支持自定义错误码与消息，全局自动捕获
+- **WebSocket 管理** — `WSConnectionManager` 支持分组、单播、广播、上下文管理器
+- **枚举基类** — `BaseEnum` 提供 `val` / `label` 属性访问
+- **SQLAlchemy 混入** — `SoftDeleteMixin` 软删除支持（可选依赖）
+- **子应用管控** — 支持动态挂载子应用，禁止子应用嵌套
+
+## 安装
+
+```bash
+pip install lumary
+```
+
+如需 SQLAlchemy 支持：
+
+```bash
+pip install lumary[sqlalchemy]
+```
+
+## 快速开始
+
+```python
+from lumary import Lumary, on_startup, on_shutdown
+
+app = Lumary(title='My Project', debug=True, enable_health_check=True)
+
+
+@on_startup(priority=100)
+async def connect_db():
+    print('Database connected')
+
+
+@on_shutdown
+async def close_db():
+    print('Database closed')
+```
+
+### WebSocket
+
+```python
+from fastapi import WebSocket
+from lumary import Lumary, WSConnectionManager
+
+app = Lumary(title='Chat')
+manager = WSConnectionManager()
+
+
+@app.websocket('/ws/{room}')
+async def ws_endpoint(websocket: WebSocket, room: str):
+    async with manager.lifespan(websocket, group=room) as cid:
+        while True:
+            data = await websocket.receive_json()
+            await manager.broadcast_json(data, group=room, exclude={cid})
+```
+
+### 统一响应
+
+```python
+from lumary import response_success, response_fail, APIResponse
+
+@app.get('/users/{uid}')
+async def get_user(uid: int) -> APIResponse:
+    user = await fetch_user(uid)
+    if not user:
+        return response_fail(code=404, message='用户不存在')
+    return response_success(data=user)
+```
+
+### 业务异常
+
+```python
+from lumary import BusinessException
+
+async def transfer(from_id: int, to_id: int, amount: float):
+    if amount <= 0:
+        raise BusinessException(code=400, message='金额必须大于零')
+    ...
+```
+
+## 模块一览
+
+| 模块 | 说明 |
+|------|------|
+| `lumary.application` | 应用类 `Lumary` |
+| `lumary.lifespan` | 生命周期钩子 `on_startup` / `on_shutdown` |
+| `lumary.schemas` | 统一响应模型 `APIResponse` / `PageData` / `PageQuery` |
+| `lumary.exceptions` | 业务异常 `BusinessException` |
+| `lumary.handlers` | 全局异常处理器 |
+| `lumary.middleware` | 中间件注册 |
+| `lumary.openapi` | 自定义 OpenAPI 文档 |
+| `lumary.websocket` | WebSocket 连接管理器 `WSConnectionManager` |
+| `lumary.common.enums` | 枚举基类 `BaseEnum` |
+| `lumary.common.mixins` | SQLAlchemy 混入类 |
+| `lumary.db` | 数据库工具 |
+
+## 开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/zarkhan/lumary.git
+cd lumary
+
+# 创建虚拟环境 & 安装开发依赖
+python -m venv .venv
+.venv\Scripts\activate       # Windows
+source .venv/bin/activate    # macOS / Linux
+pip install -e ".[dev]"
+
+# 代码检查
+ruff check lumary/
+
+# 运行测试
+pytest
+```
+
+## 打包发布
+
+```bash
+python -m build
+twine check dist/*
+twine upload dist/*
+```
+
+## License
+
+[MIT](LICENSE)

lumary-0.1.0/README.md

@@ -0,0 +1,134 @@
+# Lumary
+
+基于 FastAPI 封装的生产级 Web 应用框架，开箱即用。
+
+## 特性
+
+- **应用封装** — `Lumary` 类继承 FastAPI，内置异常处理、CORS 中间件、自定义 OpenAPI 文档、健康检查
+- **生命周期钩子** — `@on_startup` / `@on_shutdown` 装饰器，支持优先级排序与异常终止控制
+- **统一响应格式** — `APIResponse`、`PageData`、`PageQuery` 等标准化 Schema
+- **业务异常** — `BusinessException` 支持自定义错误码与消息，全局自动捕获
+- **WebSocket 管理** — `WSConnectionManager` 支持分组、单播、广播、上下文管理器
+- **枚举基类** — `BaseEnum` 提供 `val` / `label` 属性访问
+- **SQLAlchemy 混入** — `SoftDeleteMixin` 软删除支持（可选依赖）
+- **子应用管控** — 支持动态挂载子应用，禁止子应用嵌套
+
+## 安装
+
+```bash
+pip install lumary
+```
+
+如需 SQLAlchemy 支持：
+
+```bash
+pip install lumary[sqlalchemy]
+```
+
+## 快速开始
+
+```python
+from lumary import Lumary, on_startup, on_shutdown
+
+app = Lumary(title='My Project', debug=True, enable_health_check=True)
+
+
+@on_startup(priority=100)
+async def connect_db():
+    print('Database connected')
+
+
+@on_shutdown
+async def close_db():
+    print('Database closed')
+```
+
+### WebSocket
+
+```python
+from fastapi import WebSocket
+from lumary import Lumary, WSConnectionManager
+
+app = Lumary(title='Chat')
+manager = WSConnectionManager()
+
+
+@app.websocket('/ws/{room}')
+async def ws_endpoint(websocket: WebSocket, room: str):
+    async with manager.lifespan(websocket, group=room) as cid:
+        while True:
+            data = await websocket.receive_json()
+            await manager.broadcast_json(data, group=room, exclude={cid})
+```
+
+### 统一响应
+
+```python
+from lumary import response_success, response_fail, APIResponse
+
+@app.get('/users/{uid}')
+async def get_user(uid: int) -> APIResponse:
+    user = await fetch_user(uid)
+    if not user:
+        return response_fail(code=404, message='用户不存在')
+    return response_success(data=user)
+```
+
+### 业务异常
+
+```python
+from lumary import BusinessException
+
+async def transfer(from_id: int, to_id: int, amount: float):
+    if amount <= 0:
+        raise BusinessException(code=400, message='金额必须大于零')
+    ...
+```
+
+## 模块一览
+
+| 模块 | 说明 |
+|------|------|
+| `lumary.application` | 应用类 `Lumary` |
+| `lumary.lifespan` | 生命周期钩子 `on_startup` / `on_shutdown` |
+| `lumary.schemas` | 统一响应模型 `APIResponse` / `PageData` / `PageQuery` |
+| `lumary.exceptions` | 业务异常 `BusinessException` |
+| `lumary.handlers` | 全局异常处理器 |
+| `lumary.middleware` | 中间件注册 |
+| `lumary.openapi` | 自定义 OpenAPI 文档 |
+| `lumary.websocket` | WebSocket 连接管理器 `WSConnectionManager` |
+| `lumary.common.enums` | 枚举基类 `BaseEnum` |
+| `lumary.common.mixins` | SQLAlchemy 混入类 |
+| `lumary.db` | 数据库工具 |
+
+## 开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/zarkhan/lumary.git
+cd lumary
+
+# 创建虚拟环境 & 安装开发依赖
+python -m venv .venv
+.venv\Scripts\activate       # Windows
+source .venv/bin/activate    # macOS / Linux
+pip install -e ".[dev]"
+
+# 代码检查
+ruff check lumary/
+
+# 运行测试
+pytest
+```
+
+## 打包发布
+
+```bash
+python -m build
+twine check dist/*
+twine upload dist/*
+```
+
+## License
+
+[MIT](LICENSE)

lumary-0.1.0/lumary/__init__.py

@@ -0,0 +1,45 @@
+"""
+@Author     : zarkhan
+@CreateDate : 2026/5/14
+@Description: 
+"""
+from .common.enums import BaseEnum
+from .common.mixins.sqlalchemy import SoftDeleteMixin
+from .application import Lumary
+from .lifespan import on_startup, on_shutdown
+from .exceptions import BusinessException
+from .schemas import (
+    BaseSchema,
+    APIResponse,
+    PageData,
+    PageQuery,
+    response_success,
+    response_fail
+)
+from .websocket import WSConnectionManager
+
+__version__ = '0.1.0'
+
+__all__ = [
+    # 枚举基类
+    'BaseEnum',
+    # SQLAlchemy 混入类
+    'SoftDeleteMixin',
+    # 核心
+    'Lumary',
+    # 生命周期
+    'on_startup',
+    'on_shutdown',
+    # 异常
+    'BusinessException',
+    # Schema
+    'BaseSchema',
+    'APIResponse',
+    'PageQuery',
+    'PageData',
+    # 快捷函数
+    'response_success',
+    'response_fail',
+    # WebSocket连接管理器
+    'WSConnectionManager'
+]

lumary-0.1.0/lumary/application.py

@@ -0,0 +1,231 @@
+"""
+@Author     : zarkhan
+@CreateDate : 2026/5/14
+@Description: 
+"""
+from importlib import import_module
+from logging import getLogger
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import FastAPIError
+
+from .handlers import setup_exception_handlers
+from .lifespan import fastapi_lifespan
+from .middleware import setup_middlewares
+from .openapi import setup_custom_openapi
+from .schemas import APIResponse, SystemHealthInfo, response_success
+
+logger = getLogger(__name__)
+
+# ===============================
+# 默认元数据常量
+# ===============================
+_DEFAULT_TERMS_OF_SERVICE = 'https://www.zarkhan.com/terms/'
+_DEFAULT_CONTACT = {
+    'name': 'ZarkHan',
+    'url': 'https://www.zarkhan.com'
+}
+_DEFAULT_LICENSE_INFO = {
+    'name': 'MIT',
+    'url': 'https://opensource.org/licenses/MIT'
+}
+_IGNORE_DIRS = {'__pycache__', 'tests', 'test', 'utils'}
+
+
+# ===============================
+# 应用类
+# ===============================
+class Lumary(FastAPI):
+    """基于FastAPI封装的生产级Web应用类
+
+    集成：异常处理、中间件、自定义文档、子应用管控、生命周期管理
+    """
+    # 减少内存占用 + 提升属性访问速度
+    __slots__ = ('user_lifespan', 'is_sub_app')
+
+    def __init__(
+            self,
+            *,
+            debug: bool = False,
+            title: str = 'Lumary',
+            summary: str = '',
+            description: str = '',
+            version: str = '0.1.0',
+            enable_cors: bool = True,
+            allow_origins: list[str] | None = None,
+            allow_methods: list[str] | None = None,
+            allow_headers: list[str] | None = None,
+            enable_health_check: bool = False,
+            enable_access_log: bool = True,
+            **kwargs: Any
+    ):
+        """初始化
+
+        Args:
+            debug: 是否启用调试模式
+            title: 应用标题
+            summary: 应用简介
+            description: 应用描述
+            version: 应用版本
+            enable_cors: 是否启用 CORS 中间件
+            allow_origins: 允许的源列表
+            allow_methods: 允许的方法列表
+            allow_headers: 允许的头列表
+            enable_health_check: 是否启用健康检查
+            enable_access_log: 是否启用访问日志
+            **kwargs: 其他参数
+        """
+        user_lifespan = kwargs.pop('lifespan', None)
+
+        # 👇 设置默认值
+        kwargs.setdefault('terms_of_service', _DEFAULT_TERMS_OF_SERVICE)
+        kwargs.setdefault('contact', _DEFAULT_CONTACT)
+        kwargs.setdefault('license_info', _DEFAULT_LICENSE_INFO)
+        kwargs.setdefault('lifespan', fastapi_lifespan)
+
+        # 👇 如果非调试模式 → 关闭文档
+        if not debug:
+            kwargs['openapi_url'] = None
+            kwargs['docs_url'] = None
+            kwargs['redoc_url'] = None
+            kwargs['swagger_ui_oauth2_redirect_url'] = None
+
+        # 👇 调用父类初始化
+        super().__init__(
+            debug=debug,
+            title=title,
+            summary=summary,
+            description=description,
+            version=version,
+            **kwargs
+        )
+
+        # 👇 设置异常处理
+        setup_exception_handlers(self)
+
+        # 👇 设置中间件
+        setup_middlewares(
+            self,
+            enable_cors=enable_cors,
+            allow_origins=allow_origins,
+            allow_methods=allow_methods,
+            allow_headers=allow_headers
+        )
+
+        # 👇 设置自定义文档
+        setup_custom_openapi(self)
+
+        # 👇 标记当前实例不是子应用
+        self.user_lifespan = user_lifespan
+        self.is_sub_app = False
+
+        # 👇 如果启用健康检查 → 注册健康检查接口
+        if enable_health_check:
+            self._register_health_check()
+
+    def _register_health_check(self) -> None:
+        """注册健康检查接口"""
+
+        @self.get('/health', tags=['system'], summary='服务健康检查')
+        async def health(_request: Request) -> APIResponse[SystemHealthInfo]:
+            """服务健康检查
+
+            Returns:
+                响应数据
+            """
+            data = SystemHealthInfo(
+                name=self.title,
+                version=self.version,
+                debug=self.debug
+            )
+            return response_success(data=data, message='服务运行正常')
+
+    def _load_sub_app(self, module_path: str, app_name: str) -> 'Lumary | None':
+        """动态导入单个子应用
+
+        Args:
+            module_path: 模块路径
+            app_name: 应用变量名
+
+        Returns:
+            子应用实例
+        """
+        try:
+            # 动态导入模块
+            module = import_module(module_path)
+            sub_app = getattr(module, app_name, None)
+
+            # 👇 如果存在且类型正确 → 返回子应用实例
+            if isinstance(sub_app, type(self)):
+                return sub_app
+
+            logger.warning(f'The sub app {module_path}.{app_name} does not exist or is not the correct type')
+        except Exception as e:
+            logger.error(f'❌ Loading sub app module exception: {module_path}, exception info: {str(e)}')
+
+        return None
+
+    def mount(self, path: str, app: 'Lumary', name: str | None = None) -> None:
+        """挂载子应用
+
+        Args:
+            path: 挂载路径
+            app: 子应用实例
+            name:
+        """
+        # 👇 如果当前实例是子应用 → 直接报错禁止
+        if self.is_sub_app:
+            raise FastAPIError('❌ To prevent continuing to mount subapps in subapps, use APIRouter!')
+
+        # 👇 标记子应用
+        app.is_sub_app = True
+        # 警告
+        # 👇 清空子应用不允许的配置
+        if app.root_path:
+            logger.warning('The sub-app root_path has been automatically cleared')
+            app.root_path = ''
+        if app.user_lifespan:
+            logger.warning('️The sub-app lifespan has been automatically cleared')
+            app.user_lifespan = None
+
+        # 主应用 → 正常执行原生 mount
+        super().mount(path, app, name)
+        logger.info(f'🚀 The sub-app is mounted: {path} -> {app.title}')
+
+    def mount_sub_apps(self, apps_path: str | Path) -> None:
+        """挂载子应用
+
+        Args:
+            apps_path: 子应用路径
+        """
+        apps_path = Path(apps_path)
+
+        if not apps_path.exists():
+            logger.warning(f'{apps_path} 目录不存在，跳过子应用挂载')
+            return
+
+        # 👇 遍历目录
+        for path in apps_path.iterdir():
+            if not path.is_dir():
+                continue
+
+            # 👇 获取文件夹名称
+            folder_name = path.name
+
+            # 跳过以下划线/点开头 或 在忽略列表中的目录
+            if folder_name.startswith(('_', '.')) or (folder_name in _IGNORE_DIRS):
+                continue
+
+            # 👇 构建模块路径和变量名
+            module_path = f'apps.{folder_name}'
+            app_var_name = f'{folder_name}_app'
+            mount_path = f'/{folder_name}'
+
+            # 👇 动态导入子应用
+            app = self._load_sub_app(module_path, app_var_name)
+
+            # 👇 如果导入成功 → 挂载子应用
+            if app is not None:
+                self.mount(mount_path, app, folder_name)

lumary-0.1.0/lumary/common/__init__.py

@@ -0,0 +1,12 @@
+"""
+@Author     : zarkhan
+@CreateDate : 2026/5/14
+@Description: 
+"""
+from .enums import BaseEnum
+from .utils import auto_load_subapp_models
+
+__all__ = [
+    'BaseEnum',
+    'auto_load_subapp_models'
+]

lumary-0.1.0/lumary/common/enums.py

@@ -0,0 +1,29 @@
+"""
+@Author     : zarkhan
+@CreateDate : 2026/5/14
+@Description: 
+"""
+from enum import Enum
+from typing import Any
+
+
+class BaseEnum(Enum):
+    """枚举基类"""
+
+    @property
+    def val(self) -> Any:
+        """获取枚举值
+
+        Returns:
+            枚举值
+        """
+        return self.value[0]
+
+    @property
+    def label(self) -> str:
+        """获取枚举标签
+
+        Returns:
+            枚举描述标签
+        """
+        return self.value[1]  # 取描述

lumary-0.1.0/lumary/common/mixins/__init__.py

@@ -0,0 +1,8 @@
+"""
+@Author     : zarkhan
+@CreateDate : 2026/5/14
+@Description: 
+"""
+from .sqlalchemy import SoftDeleteMixin
+
+__all__ = ['SoftDeleteMixin']

lumary-0.1.0/lumary/common/mixins/sqlalchemy.py

@@ -0,0 +1,28 @@
+"""
+@Author     : zarkhan
+@CreateDate : 2026/5/14
+@Description: 
+"""
+from datetime import datetime
+
+from sqlalchemy import DateTime, Boolean
+from sqlalchemy.orm import Mapped, mapped_column
+
+
+class SoftDeleteMixin:
+    """SQLAlchemy 软删除混入类
+
+    为业务模型提供 `is_deleted` 和 `deleted_at` 字段，
+    用于实现逻辑删除，以保证数据的完整性和可追溯性
+    """
+    is_deleted: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        comment='是否删除'
+    )
+
+    deleted_at: Mapped[datetime | None] = mapped_column(
+        DateTime,
+        nullable=True,
+        comment='删除时间'
+    )