magic-base 0.1.2__tar.gz → 0.1.3__tar.gz

{magic_base-0.1.2/src/magic_base.egg-info → magic_base-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: magic-base
-Version: 0.1.2
+Version: 0.1.3
 Summary: Magic 平台公共基类库 - 提供统一的抽象基类和核心接口
 Author: wxd123
 License-Expression: MIT

{magic_base-0.1.2 → magic_base-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "magic-base"
-version = "0.1.2"
+version = "0.1.3"
 description = "Magic 平台公共基类库 - 提供统一的抽象基类和核心接口"
 readme = "README.md"
 authors = [{name = "wxd123"}]

{magic_base-0.1.2 → magic_base-0.1.3}/src/magic_base/__init__.py

@@ -4,6 +4,7 @@ from magic_base.config.base_config import BaseConfig
 from magic_base.data_access.config.base_database_config import BaseDatabaseConfig, MagicDatabaseConfig
 from magic_base.data_access.manager.base_database_manager import BaseDatabaseManager, MagicDatabaseManager
 from magic_base.data_access.model.base_entity import Base, BaseEntity, MagicBaseEntity
+from magic_base.data_access.model.base_dataclass import BaseDataClass
 from magic_base.data_access.repository.base_repository import BaseRepository, MagicBaseRepository
 from magic_base.data_access.service.base_service import BaseService, MagicBaseService
 from magic_base.context.application_context import ApplicationContext
@@ -13,6 +14,7 @@ __all__ = [
     'BaseConfig', 'BaseDatabaseConfig', 'MagicDatabaseConfig',
     'BaseDatabaseManager', 'MagicDatabaseManager',
     'Base', 'BaseEntity', 'MagicBaseEntity', 
+    'BaseDataClass',
     'BaseRepository', 'MagicBaseRepository',
     'BaseService', 'MagicBaseService',
     'CSVValidator'

magic_base-0.1.3/src/magic_base/config/base_config.py

@@ -0,0 +1,155 @@
+# magic_base/config/base_config.py
+"""
+配置管理基类
+
+提供配置管理的抽象接口，定义了配置获取、设置、加载、保存和重载的标准方法。
+所有具体配置管理实现都应继承此类并实现其抽象方法。
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+
+
+class BaseConfig(ABC):
+    """
+    配置管理基类（抽象类）
+    
+    定义了配置管理器的标准接口，包括配置的读取、写入、持久化等操作。
+    子类需要实现具体的配置存储方式（如文件、数据库、远程配置中心等）。
+    
+    使用示例:
+        class MyConfig(BaseConfig):
+            def get(self, key: str, default: Any = None) -> Any:
+                # 实现获取配置逻辑
+                return self._config.get(key, default)
+            
+            def set(self, key: str, value: Any) -> None:
+                # 实现设置配置逻辑
+                self._config[key] = value
+            
+            def load(self) -> Dict[str, Any]:
+                # 实现加载配置逻辑
+                return self._config
+            
+            def save(self) -> bool:
+                # 实现保存配置逻辑
+                return True
+            
+            def reload(self) -> None:
+                # 实现重载配置逻辑
+                self.load()
+    """
+    
+    @abstractmethod
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        获取配置值
+        
+        根据指定的键名获取对应的配置值。如果键不存在，返回默认值。
+        
+        Args:
+            key (str): 配置键名，支持点号分隔的嵌套键（如 'database.host'）
+            default (Any, optional): 当键不存在时返回的默认值。默认为 None
+        
+        Returns:
+            Any: 配置值，如果键不存在则返回 default 参数指定的值
+        
+        Raises:
+            KeyError: 当键不存在且未提供 default 参数时可能抛出（具体取决于子类实现）
+        
+        Example:
+            >>> config.get('app.name')
+            'MyApp'
+            >>> config.get('app.timeout', 30)
+            30
+        """
+        pass
+    
+    @abstractmethod
+    def set(self, key: str, value: Any) -> None:
+        """
+        设置配置值
+        
+        将指定的键值对写入配置中。如果键已存在，则覆盖原有值；
+        如果键不存在，则创建新配置项。
+        
+        Args:
+            key (str): 配置键名，支持点号分隔的嵌套键（如 'database.host'）
+            value (Any): 要设置的配置值，可以是任意可序列化的 Python 对象
+        
+        Raises:
+            TypeError: 当 value 类型不被支持时抛出
+            ValueError: 当 key 格式无效时抛出
+        
+        Example:
+            >>> config.set('app.debug', True)
+            >>> config.set('database.port', 3306)
+        """
+        pass
+    
+    @abstractmethod
+    def load(self) -> Dict[str, Any]:
+        """
+        加载配置
+        
+        从存储介质（如文件、数据库等）中读取配置数据并加载到内存中。
+        通常用于初始化或手动触发配置加载。
+        
+        Returns:
+            Dict[str, Any]: 加载后的配置字典，包含所有配置项
+        
+        Raises:
+            FileNotFoundError: 当配置文件不存在时抛出
+            PermissionError: 当没有读取权限时抛出
+            json.JSONDecodeError: 当配置文件格式错误时抛出（针对 JSON 格式）
+        
+        Example:
+            >>> config = MyConfig()
+            >>> config.load()
+            {'app': {'name': 'MyApp', 'version': '1.0'}}
+        """
+        pass
+    
+    @abstractmethod
+    def save(self) -> bool:
+        """
+        保存配置
+        
+        将当前内存中的配置持久化到存储介质中（如文件、数据库等）。
+        
+        Returns:
+            bool: 保存成功返回 True，失败返回 False
+        
+        Raises:
+            PermissionError: 当没有写入权限时抛出
+            IOError: 当写入过程中发生 I/O 错误时抛出
+        
+        Example:
+            >>> if config.save():
+            ...     print("配置保存成功")
+            ... else:
+            ...     print("配置保存失败")
+        """
+        pass
+    
+    @abstractmethod
+    def reload(self) -> None:
+        """
+        重新加载配置
+        
+        丢弃当前内存中的配置，重新从存储介质加载最新的配置数据。
+        通常用于配置热更新场景。
+        
+        注意：重新加载会覆盖所有未保存的配置修改，请谨慎使用。
+        
+        Raises:
+            FileNotFoundError: 当配置文件不存在时抛出
+            PermissionError: 当没有读取权限时抛出
+        
+        Example:
+            >>> # 配置文件被外部修改后
+            >>> config.reload()  # 重新加载最新配置
+            >>> config.get('app.debug')
+            True
+        """
+        pass

magic_base-0.1.3/src/magic_base/data_access/model/base_dataclass.py

@@ -0,0 +1,169 @@
+# magic_base/data_access/model/base_dataclass.py
+from dataclasses import dataclass, asdict, fields, is_dataclass
+from typing import Dict, Any, TypeVar, Type, Union
+import json
+
+
+T = TypeVar('T', bound='BaseDataClass')
+
+
+class BaseDataClass:
+    """
+    数据类基类
+    
+    提供 to_dict、from_dict、update_from_dict 等通用方法。
+    所有使用 @dataclass 装饰的类都应该继承此类。
+    
+    使用示例：
+        @dataclass
+        class ProjectInfo(BaseDataClass):
+            name: str
+            version: str = "1.0.0"
+        
+        # 转换
+        project = ProjectInfo(name="test")
+        data = project.to_dict()  # {'name': 'test', 'version': '1.0.0'}
+        
+        # 创建
+        new_project = ProjectInfo.from_dict({'name': 'test', 'version': '2.0.0'})
+        
+        # 更新
+        project.update_from_dict({'version': '2.0.0'})
+    """
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        将数据类实例转换为字典
+        
+        Returns:
+            Dict[str, Any]: 包含所有字段的字典，嵌套的数据类也会被递归转换
+            
+        Example:
+            >>> @dataclass
+            ... class SubConfig(BaseDataClass):
+            ...     key: str
+            ... 
+            >>> @dataclass
+            ... class MainConfig(BaseDataClass):
+            ...     name: str
+            ...     sub: SubConfig
+            ... 
+            >>> main = MainConfig(name="test", sub=SubConfig(key="value"))
+            >>> main.to_dict()
+            {'name': 'test', 'sub': {'key': 'value'}}
+        """
+        return self._to_dict_recursive(self)
+    
+    def _to_dict_recursive(self, obj: Any) -> Any:
+        """递归转换嵌套的数据类"""
+        if is_dataclass(obj):
+            result = {}
+            for field in fields(obj):
+                value = getattr(obj, field.name)
+                result[field.name] = self._to_dict_recursive(value)
+            return result
+        elif isinstance(obj, list):
+            return [self._to_dict_recursive(item) for item in obj]
+        elif isinstance(obj, dict):
+            return {k: self._to_dict_recursive(v) for k, v in obj.items()}
+        else:
+            return obj
+    
+    @classmethod
+    def from_dict(cls: Type[T], data: Dict[str, Any]) -> T:
+        """
+        从字典创建数据类实例
+        
+        Args:
+            data: 包含字段的字典
+            
+        Returns:
+            T: 数据类实例
+        """
+        if not is_dataclass(cls):
+            raise TypeError(f"{cls.__name__} 必须是 dataclass")
+        
+        return cls._from_dict_recursive(cls, data)
+    
+    @classmethod
+    def _from_dict_recursive(cls, target_class: Type, data: Dict[str, Any]) -> Any:
+        """递归创建嵌套的数据类"""
+        if not is_dataclass(target_class):
+            return data
+        
+        field_types = {f.name: f.type for f in fields(target_class)}
+        processed = {}
+        
+        for field_name, field_value in data.items():
+            if field_name not in field_types:
+                continue
+            
+            field_type = field_types[field_name]
+            # 处理 Optional 类型（简化处理）
+            if hasattr(field_type, '__origin__') and field_type.__origin__ is Union:
+                # 提取 Union 中的实际类型
+                for arg in field_type.__args__:
+                    if is_dataclass(arg):
+                        field_type = arg
+                        break
+            
+            if is_dataclass(field_type):
+                processed[field_name] = cls._from_dict_recursive(field_type, field_value)
+            elif isinstance(field_value, list) and field_value:
+                # 处理列表中的嵌套数据类
+                processed[field_name] = [
+                    cls._from_dict_recursive(field_type.__args__[0], item) 
+                    if hasattr(field_type, '__args__') and is_dataclass(field_type.__args__[0])
+                    else item
+                    for item in field_value
+                ]
+            else:
+                processed[field_name] = field_value
+        
+        return target_class(**processed)
+    
+    def update_from_dict(self, data: Dict[str, Any]) -> 'BaseDataClass':
+        """
+        从字典更新当前实例
+        
+        Args:
+            data: 包含待更新字段的字典
+            
+        Returns:
+            BaseDataClass: 当前实例（支持链式调用）
+        """
+        for key, value in data.items():
+            if hasattr(self, key):
+                current_value = getattr(self, key)
+                # 如果当前值是数据类，且新值也是字典，递归更新
+                if is_dataclass(current_value) and isinstance(value, dict):
+                    current_value.update_from_dict(value)
+                else:
+                    setattr(self, key, value)
+        return self
+    
+    def to_json(self, indent: int = None) -> str:
+        """
+        转换为 JSON 字符串
+        
+        Args:
+            indent: JSON 缩进空格数
+            
+        Returns:
+            str: JSON 字符串
+        """
+        return json.dumps(self.to_dict(), ensure_ascii=False, indent=indent)
+    
+    @classmethod
+    def from_json(cls: Type[T], json_str: str) -> T:
+        """
+        从 JSON 字符串创建实例
+        
+        Args:
+            json_str: JSON 字符串
+            
+        Returns:
+            T: 数据类实例
+        """
+        data = json.loads(json_str)
+        return cls.from_dict(data)

{magic_base-0.1.2 → magic_base-0.1.3}/src/magic_base/data_access/repository/base_repository.py

@@ -5,8 +5,8 @@ from typing import Dict, List, Optional, TypeVar, Generic, Type, Any, get_origin
 from sqlalchemy.orm import Session
 from sqlalchemy import inspect, text
 
-from .base_repository_cud_mixin import CUDRepositoryMixin
-from .base_repository_query_mixin import QueryRepositoryMixin
+from .mixin.base_repository_cud_mixin import CUDRepositoryMixin
+from .mixin.base_repository_query_mixin import QueryRepositoryMixin
 
 
 T = TypeVar('T')

magic_base-0.1.3/src/magic_base/data_access/repository/base_tree_repository.py

@@ -0,0 +1,50 @@
+# magic_base/data_access/repository/base_tree_repository.py
+"""
+BaseTreeRepository - 树结构专属 Repository 基类
+
+定位：
+    MagicBaseRepository + TreeRepositoryMixin 的预设组合。
+    层次表专属 Repository 直接继承即用。
+
+使用方式：
+    class SystemHierarchyDefRepository(BaseTreeRepository[SystemHierarchyDefs]):
+        pass
+
+等价于：
+    class SystemHierarchyDefRepository(
+        MagicBaseRepository[SystemHierarchyDefs],
+        TreeRepositoryMixin[SystemHierarchyDefs],
+    ):
+        pass
+"""
+
+from typing import TypeVar
+
+from .base_repository import MagicBaseRepository
+from .mixin.base_tree_repository_mixin import TreeRepositoryMixin
+
+
+T = TypeVar('T')
+
+
+class BaseTreeRepository(
+    MagicBaseRepository[T],
+    TreeRepositoryMixin[T],
+):
+    """
+    树结构专属 Repository 基类
+
+    组合：
+        - MagicBaseRepository：通用 CRUD（CUD + Query）
+        - TreeRepositoryMixin：树专属数据访问
+
+    提供能力：
+        - 通用：create / update / delete / find / find_one / count / paginate
+        - 树专属：find_edge / find_children / find_parents / has_parent
+                 / find_subtree_by_path / find_edges_by_parents
+                 / find_ancestor_path / is_descendant / get_max_order_no
+
+    注意：
+        通常通过子类继承使用，子类需指定泛型类型 T（层次表 ORM 模型）。
+    """
+    pass

magic_base-0.1.3/src/magic_base/data_access/repository/base_vector_repository.py

@@ -0,0 +1,53 @@
+# magic_base/data_access/repository/base_vector_repository.py
+"""
+BaseVectorRepository - 向量结构专属 Repository 基类
+
+定位：
+    MagicBaseRepository + VectorRepositoryMixin 的预设组合。
+    向量表专属 Repository 直接继承即用。
+
+使用方式：
+    class SystemModelMemberVectorRepository(
+        BaseVectorRepository[SystemModelMemberVectors]
+    ):
+        pass
+
+等价于：
+    class SystemModelMemberVectorRepository(
+        MagicBaseRepository[SystemModelMemberVectors],
+        VectorRepositoryMixin[SystemModelMemberVectors],
+    ):
+        pass
+"""
+
+from typing import TypeVar
+
+from .base_repository import MagicBaseRepository
+from .mixin.base_vector_repository_mixin import VectorRepositoryMixin
+
+
+T = TypeVar('T')
+
+
+class BaseVectorRepository(
+    MagicBaseRepository[T],
+    VectorRepositoryMixin[T],
+):
+    """
+    向量结构专属 Repository 基类
+
+    组合：
+        - MagicBaseRepository：通用 CRUD（CUD + Query）
+        - VectorRepositoryMixin：向量专属数据访问
+
+    提供能力：
+        - 通用：create / update / delete / find / find_one / count / paginate
+        - 向量专属：find_vector / find_vectors_by_owner
+                   / list_encodings / delete_vector
+
+    注意：
+        通常通过子类继承使用，子类需指定泛型类型 T（向量表 ORM 模型）。
+        默认字段名：member_key / vector_encoding_key / vector_encoding_value。
+        如需自定义字段名，调用时传 owner_field / encoding_field。
+    """
+    pass