hframe 0.1.0__py3-none-any.whl

hframe/__init__.py

@@ -0,0 +1,108 @@
+"""
+hframe — 分层架构后端框架
+
+架构链路：View(可选) → Handler → Service → Repository → DB
+
+核心暴露：
+- Config: 全局配置
+- GenericHandler: HTTP 无关的业务编排层（级联/事务/权限）
+- GenericService: 单实体生命周期（before/do/after 钩子）
+- BaseRepository: 数据访问唯一出口
+
+工具暴露：
+- util.crypto: md5, crypt, make_id
+- util.data: build_tree, copy_dict, check_data_type
+- util.format: to_snake_case, to_camel_case, json_dumps, Serialize
+- util.transform: is_integer, set_default_int, trans_str_to_arr
+- util.yaml_util: read_yaml_file, write_yaml_file
+- util.auth: UserService（登录/注册/身份）
+- util.verify: CodeService（验证码）
+"""
+
+__version__ = "0.1.0"
+
+# ========== 核心配置 ==========
+from .config import Config
+
+# ========== 类型化异常 ==========
+from .exceptions import (
+    HFrameException,
+    ValidationException,
+    UniqueValidationException,
+    NotFoundException,
+    UnauthorizedException,
+    PermissionException,
+    ServiceException,
+    ConflictException,
+    ForbiddenOperationException,
+    RepositoryException,
+    InfrastructureException,
+    is_exception,
+    get_exception_code,
+)
+
+# ========== 日志 ==========
+from .logging import LogUtil
+
+# ========== Repository 层 ==========
+from .repository import BaseRepository, VersionRepository, ListFilters, Filter, FilterOp
+
+# ========== Service 层 ==========
+from .service import GenericService, ServiceConfig, ServiceHooks, CrudRequest, VersionFieldMapping
+
+# ========== Handler 层（核心暴露） ==========
+from .handler import (
+    GenericHandler,
+    HandlerConfig,
+    HandlerHooks,
+    CascadeRelation,
+    ReferenceRelation,
+    ChildRefRelation,
+    GetRequest,
+    MapRequest,
+    RequestFactory,
+)
+
+# ========== 工具层 ==========
+from .util import UserService, CodeService
+from .util import crypto, data, format, transform, yaml_util
+
+# ========== 注册表 ==========
+from .registry import Registry, EntityConfig
+
+# ========== Django View 层（可选） ==========
+try:
+    from .view import (
+        BaseView, ModuleView, ListView, DetailView, EditView, DeleteView,
+        H5BaseView, H5ModuleView, H5ListView, H5DetailView, H5EditView, H5DeleteView, H5Mixin,
+    )
+except ImportError:
+    pass
+
+__all__ = [
+    # 版本
+    '__version__',
+    # 配置
+    'Config',
+    # 异常
+    'HFrameException', 'ValidationException', 'UniqueValidationException',
+    'NotFoundException', 'UnauthorizedException', 'PermissionException',
+    'ServiceException', 'ConflictException', 'ForbiddenOperationException',
+    'RepositoryException', 'InfrastructureException',
+    'is_exception', 'get_exception_code',
+    # 日志
+    'LogUtil',
+    # Repository
+    'BaseRepository', 'VersionRepository', 'ListFilters', 'Filter', 'FilterOp',
+    # Service
+    'GenericService', 'ServiceConfig', 'ServiceHooks', 'CrudRequest', 'VersionFieldMapping',
+    # Handler（核心）
+    'GenericHandler', 'HandlerConfig', 'HandlerHooks',
+    'CascadeRelation', 'ReferenceRelation', 'ChildRefRelation',
+    'GetRequest', 'MapRequest', 'RequestFactory',
+    # 注册表
+    'Registry', 'EntityConfig',
+    # 工具
+    'UserService', 'CodeService',
+    'crypto', 'data', 'format', 'transform', 'yaml_util',
+]

hframe/config.py

@@ -0,0 +1,107 @@
+"""
+hframe 配置模块
+
+集中管理所有配置：数据库、缓存、应用基础信息等。
+支持从 YAML 文件加载并深度合并默认配置。
+"""
+
+import os
+import yaml
+from typing import Any, Dict
+
+
+# 默认配置（可作为开发环境的兜底）
+_DEFAULTS: Dict[str, Any] = {
+    "BASE_INFO": {
+        "secret_key": "py_crux_default_secret",
+        "datetime_format": "%Y-%m-%d %H:%M:%S",
+        "auth_token_expire_time": 3600,
+        "admin_role_id": -1,
+        "check_page_permission": 0,
+        "user_tables": {},
+    },
+    "MYSQL_INFO": {
+        "host": "localhost",
+        "port": 3306,
+        "user": "root",
+        "password": "",
+        "database": "test",
+        "charset": "utf8mb4",
+    },
+    "REDIS_INFO": {
+        "host": "localhost",
+        "port": 6379,
+        "password": "",
+        "db": 0,
+    },
+    "SSH_INFO": {},
+    "WECHAT_INFO": {},
+}
+
+
+def _deep_merge(source: Dict, dest: Dict) -> Dict:
+    """深度合并字典，source 覆盖 dest"""
+    for key, value in source.items():
+        if key in dest and isinstance(value, dict) and isinstance(dest[key], dict):
+            _deep_merge(value, dest[key])
+        else:
+            dest[key] = value
+    return dest
+
+
+class Config:
+    """
+    全局配置容器
+
+    使用方式：
+        Config.BASE_INFO['secret_key']
+        Config.MYSQL_INFO['host']
+
+    初始化：
+        Config.load('config.yaml')  # 从 YAML 加载并深度合并默认值
+    """
+
+    BASE_INFO: Dict[str, Any] = dict(_DEFAULTS["BASE_INFO"])
+    MYSQL_INFO: Dict[str, Any] = dict(_DEFAULTS["MYSQL_INFO"])
+    REDIS_INFO: Dict[str, Any] = dict(_DEFAULTS["REDIS_INFO"])
+    SSH_INFO: Dict[str, Any] = dict(_DEFAULTS["SSH_INFO"])
+    WECHAT_INFO: Dict[str, Any] = dict(_DEFAULTS["WECHAT_INFO"])
+
+    @classmethod
+    def load(cls, file_path: str = "config.yaml"):
+        """
+        从 YAML 文件加载配置，与默认值深度合并
+
+        Args:
+            file_path: YAML 配置文件路径，支持相对路径和绝对路径
+        """
+        if not os.path.exists(file_path):
+            return
+
+        with open(file_path, 'r', encoding='utf-8') as f:
+            user_config = yaml.safe_load(f) or {}
+
+        # 深度合并：用户配置覆盖默认值
+        for section in ("BASE_INFO", "MYSQL_INFO", "REDIS_INFO", "SSH_INFO", "WECHAT_INFO"):
+            if section in user_config:
+                _deep_merge(user_config[section], cls.__dict__[section])
+
+    @classmethod
+    def reset(cls):
+        """重置为默认配置"""
+        cls.BASE_INFO = dict(_DEFAULTS["BASE_INFO"])
+        cls.MYSQL_INFO = dict(_DEFAULTS["MYSQL_INFO"])
+        cls.REDIS_INFO = dict(_DEFAULTS["REDIS_INFO"])
+        cls.SSH_INFO = dict(_DEFAULTS["SSH_INFO"])
+        cls.WECHAT_INFO = dict(_DEFAULTS["WECHAT_INFO"])
+
+    @classmethod
+    def get(cls, key: str, default: Any = None) -> Any:
+        """快捷取值：Config.get('BASE_INFO.secret_key')"""
+        parts = key.split('.')
+        obj = cls
+        for part in parts:
+            obj = getattr(obj, part, None) if hasattr(obj, part) else (obj.get(part) if isinstance(obj, dict) else None)
+            if obj is None:
+                return default
+        return obj

hframe/exceptions.py

@@ -0,0 +1,126 @@
+"""
+hframe 类型化异常体系
+
+借鉴 Go 项目哨兵错误模式，用 Python 的异常类继承体系实现。
+每个异常类型携带业务码和消息，支持精确匹配（类比 errors.Is()）。
+"""
+
+
+class HFrameException(Exception):
+    """框架基础异常"""
+
+    def __init__(self, message: str = "", code: int = 500):
+        self.message = message
+        self.code = code
+        super().__init__(message)
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}(code={self.code}, message={self.message})"
+
+
+# ============================================================
+# 校验类异常（客户端可修正）
+# ============================================================
+
+class ValidationException(HFrameException):
+    """数据校验失败"""
+
+    def __init__(self, message: str = "数据校验失败"):
+        super().__init__(message=message, code=400)
+
+
+class UniqueValidationException(HFrameException):
+    """唯一性校验失败"""
+
+    def __init__(self, message: str = "唯一性校验失败"):
+        super().__init__(message=message, code=409)
+
+
+class NotFoundException(HFrameException):
+    """资源不存在"""
+
+    def __init__(self, message: str = "资源不存在"):
+        super().__init__(message=message, code=404)
+
+
+# ============================================================
+# 权限/认证类异常
+# ============================================================
+
+class UnauthorizedException(HFrameException):
+    """未认证（需要登录）"""
+
+    def __init__(self, message: str = "未认证"):
+        super().__init__(message=message, code=401)
+
+
+class PermissionException(HFrameException):
+    """无权限（认证了但权限不足）"""
+
+    def __init__(self, message: str = "权限不足"):
+        super().__init__(message=message, code=403)
+
+
+# ============================================================
+# 业务类异常
+# ============================================================
+
+class ServiceException(HFrameException):
+    """Service 层业务异常（通用）"""
+
+    def __init__(self, message: str = "服务异常"):
+        super().__init__(message=message, code=500)
+
+
+class ConflictException(HFrameException):
+    """状态冲突（如版本已发布）"""
+
+    def __init__(self, message: str = "状态冲突"):
+        super().__init__(message=message, code=409)
+
+
+class ForbiddenOperationException(HFrameException):
+    """操作被禁止（业务规则限制）"""
+
+    def __init__(self, message: str = "操作被禁止"):
+        super().__init__(message=message, code=403)
+
+
+# ============================================================
+# 基础设施类异常
+# ============================================================
+
+class RepositoryException(HFrameException):
+    """Repository 层数据访问异常"""
+
+    def __init__(self, message: str = "数据访问异常"):
+        super().__init__(message=message, code=500)
+
+
+class InfrastructureException(HFrameException):
+    """基础设施异常（DB连接、Redis连接等）"""
+
+    def __init__(self, message: str = "基础设施异常"):
+        super().__init__(message=message, code=500)
+
+
+# ============================================================
+# 辅助：异常匹配函数（类比 Go 的 errors.Is）
+# ============================================================
+
+def is_exception(exc: Exception, target_type: type) -> bool:
+    """
+    判断异常是否为指定类型（含子类）
+
+    用法：
+        if is_exception(e, NotFoundException):
+            # 处理未找到的情况
+    """
+    return isinstance(exc, target_type)
+
+
+def get_exception_code(exc: Exception) -> int:
+    """获取异常的业务码（非 HFrameException 返回 500）"""
+    if isinstance(exc, HFrameException):
+        return exc.code
+    return 500

hframe/handler/__init__.py

@@ -0,0 +1,13 @@
+"""Handler 层 — HTTP 无关的业务编排层"""
+
+from .config import HandlerConfig, CascadeRelation, ReferenceRelation, ChildRefRelation
+from .generic import GenericHandler
+from .hooks import HandlerHooks
+from .request import GetRequest, MapRequest, RequestFactory
+
+__all__ = [
+    'HandlerConfig', 'CascadeRelation', 'ReferenceRelation', 'ChildRefRelation',
+    'GenericHandler',
+    'HandlerHooks',
+    'GetRequest', 'MapRequest', 'RequestFactory',
+]

hframe/handler/config.py

@@ -0,0 +1,108 @@
+"""
+Handler 配置
+
+定义 Handler 层的配置项：级联关系、请求工厂、认证/权限钩子等。
+借鉴 Go 项目 HandlerConfig[M] 的设计，去掉泛型和 gin 绑定。
+"""
+
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+
+class CascadeRelation:
+    """
+    级联关系声明（向下：父→子）
+
+    配置后，Handler 在 Create/Delete/Get/List 时自动处理子表联动。
+    """
+
+    def __init__(self, *,
+                 child_table: str,
+                 parent_fk_field: str,
+                 child_fk_field: str,
+                 child_columns: List[str] = None,
+                 show_name: str = "",
+                 on_delete: str = "cascade"):  # cascade | soft_delete | restrict
+        self.child_table = child_table
+        self.parent_fk_field = parent_fk_field    # 父表中指向子表的FK字段名
+        self.child_fk_field = child_fk_field      # 子表中指向父表的FK字段名
+        self.child_columns = child_columns or ["id", "name"]
+        self.show_name = show_name or child_table
+        self.on_delete = on_delete
+
+
+class ReferenceRelation:
+    """
+    向上级联声明（子→父）
+
+    配置后，Get/List 查询时自动解析逻辑外键字段（如 site_ulid→site），
+    并将解析结果挂到返回 dict 的对应键下。
+    """
+
+    def __init__(self, *,
+                 parent_table: str,
+                 fk_field: str,         # 本实体中的外键字段名
+                 parent_pk_field: str = "id",
+                 parent_columns: List[str] = None,
+                 show_name: str = "",
+                 parent_service_name: str = ""):
+        self.parent_table = parent_table
+        self.fk_field = fk_field
+        self.parent_pk_field = parent_pk_field
+        self.parent_columns = parent_columns or ["id", "name"]
+        self.show_name = show_name or parent_table
+        self.parent_service_name = parent_service_name
+
+
+class ChildRefRelation:
+    """
+    向下引用声明（父→子 FK 列表）
+
+    配置后，Get/List 查询时自动将 FK 列表（如 tag_ulids: [1,2,3]）
+    批量解析为完整对象列表。
+    与 CascadeRelation 不同：仅关联已有实体，不参与级联创建/删除/更新。
+    """
+
+    def __init__(self, *,
+                 child_table: str,
+                 fk_list_field: str,    # 父实体中存放子ID列表的字段名
+                 child_pk_field: str = "id",
+                 child_columns: List[str] = None,
+                 show_name: str = "",
+                 child_service_name: str = ""):
+        self.child_table = child_table
+        self.fk_list_field = fk_list_field
+        self.child_pk_field = child_pk_field
+        self.child_columns = child_columns or ["id", "name"]
+        self.show_name = show_name or child_table
+        self.child_service_name = child_service_name
+
+
+class HandlerConfig:
+    """
+    Handler 配置
+
+    每个实体类型创建一个 Handler 实例时附带一份配置。
+    """
+
+    def __init__(self, *,
+                 entity_name: str = "",
+                 cascades: List[CascadeRelation] = None,
+                 references: List[ReferenceRelation] = None,
+                 child_refs: List[ChildRefRelation] = None,
+                 auth: Callable = None,
+                 perm: Callable = None):
+        """
+        Args:
+            entity_name: 实体名（用于日志和错误信息）
+            cascades: 级联关系列表
+            references: 向上级联引用列表
+            child_refs: 向下子引用列表
+            auth: 认证钩子 Callable，接收请求上下文返回 user_info
+            perm: 权限校验钩子 Callable，接收 (user_info, resource, action) 返回 bool
+        """
+        self.entity_name = entity_name
+        self.cascades = cascades or []
+        self.references = references or []
+        self.child_refs = child_refs or []
+        self.auth = auth
+        self.perm = perm