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

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

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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "magic-base"
-version = "0.1.0"
+version = "0.1.2"
 description = "Magic 平台公共基类库 - 提供统一的抽象基类和核心接口"
 readme = "README.md"
 authors = [{name = "wxd123"}]
@@ -43,5 +43,14 @@ Repository = "https://github.com/wxd123/magic-base.git"
 [dependency-groups]
 dev = [
     "build>=1.4.4",
+    "magic-base",
     "twine>=6.2.0",
 ]
+
+[tool.uv.workspace]
+members = [
+    ".",
+]
+
+[tool.uv.sources]
+magic-base = { workspace = true, editable = true }

magic_base-0.1.2/src/magic_base/__init__.py

@@ -0,0 +1,19 @@
+# magic_base/__init__.py
+
+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.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
+from magic_base.utils.base_csv_validator import CSVValidator
+__all__ = [
+    'ApplicationContext', 
+    'BaseConfig', 'BaseDatabaseConfig', 'MagicDatabaseConfig',
+    'BaseDatabaseManager', 'MagicDatabaseManager',
+    'Base', 'BaseEntity', 'MagicBaseEntity', 
+    'BaseRepository', 'MagicBaseRepository',
+    'BaseService', 'MagicBaseService',
+    'CSVValidator'
+]

{magic_base-0.1.0 → magic_base-0.1.2}/src/magic_base/config/base_config.py

@@ -1,4 +1,4 @@
-# magic_base/config/base.py
+# magic_base/config/base_config.py
 """
 配置管理基类
 """
@@ -7,7 +7,7 @@ from abc import ABC, abstractmethod
 from typing import Any, Dict, Optional
 
 
-class ConfigBase(ABC):
+class BaseConfig(ABC):
     """配置管理基类"""
     
     @abstractmethod

magic_base-0.1.2/src/magic_base/constants/tables.py

@@ -0,0 +1,10 @@
+# magic_base/constants/tables.py
+"""数据库表名常量"""
+
+
+
+
+# 辅助表
+SCHEMA_VERSION_TABLE = 'magic_schema_version'
+
+

magic_base-0.1.2/src/magic_base/context/application_context.py

@@ -0,0 +1,160 @@
+# magic_base/core/context.py
+
+import threading
+from typing import Optional, Generic, TypeVar, Dict
+
+from magic_base.data_access.config.base_database_config import BaseDatabaseConfig
+from magic_base.data_access.manager.base_database_manager import BaseDatabaseManager
+
+
+# 定义泛型变量
+ContextType = TypeVar('ContextType')
+
+class ApplicationContext(Generic[ContextType]):
+    """全局应用上下文 - 泛型基类
+    
+    提供全局单例级别的上下文管理，支持数据库配置、数据库管理器以及项目特定的上下文信息。
+    使用线程锁保证多线程环境下的线程安全。
+    
+    每个项目可以继承此类并指定自己的上下文类型，从而获得类型安全的上下文访问。
+    
+    泛型参数:
+        ContextType: 项目特定上下文的类型，可以是任何自定义类或数据结构
+    
+    类属性:
+        _lock: 线程锁，用于保证初始化与重置操作的原子性
+        db_config: 数据库配置对象，用于存储数据库连接参数
+        db_manager: 数据库管理器对象，用于执行数据库操作
+        _contexts: 项目特定的上下文对象，类型由泛型参数ContextType决定
+    
+    使用示例:
+        # 定义项目特定上下文类
+        class MyContext:
+            user_id: str
+            tenant_id: str
+        
+        # 初始化全局上下文
+        ApplicationContext[MyContext].initialize(
+            db_config=my_db_config,
+            db_manager=my_db_manager,
+            context=MyContext(user_id="123", tenant_id="tenant1")
+        )
+        
+        # 获取上下文
+        ctx = ApplicationContext[MyContext].get_context()
+        db_mgr = ApplicationContext[MyContext].get_db_manager()
+    """
+    
+    _lock = threading.Lock()
+    
+    # 共享属性（所有项目都需要）
+    db_config: Optional[BaseDatabaseConfig] = None
+    """数据库配置对象，可选，未设置时为None"""
+    
+    db_manager: Optional[BaseDatabaseManager] = None
+    """数据库管理器对象，可选，未设置时为None"""
+    
+    
+    # 业务上下文字典（按 key 存储）
+    _contexts: Dict[str, ContextType] = {}
+    """项目特定上下文对象，类型由泛型参数ContextType决定，未设置时为None"""
+    
+    @classmethod
+    def initialize(cls, 
+                   project_name: str,
+                   db_config: Optional[BaseDatabaseConfig] = None,
+                   db_manager: Optional[BaseDatabaseManager] = None,
+                   context: Optional[ContextType] = None):
+        """初始化全局上下文
+        
+        使用线程锁保证初始化操作的线程安全性。允许部分初始化，即可以只设置部分属性，
+        未传入的参数对应的属性将保持原值不变（如果之前已设置）或保持为None。
+        
+        参数:
+            project_name: 项目名称，用于区分各个模块的自定义上下文
+            db_config: 数据库配置对象，可选，如果提供则替换现有的db_config
+            db_manager: 数据库管理器对象，可选，如果提供则替换现有的db_manager
+            context: 项目特定的上下文对象，可选，如果提供则替换现有的context
+        
+        注意:
+            此方法不是全量替换，而是增量更新。若希望完全重置所有属性，请先调用reset()方法。
+        
+        示例:
+            # 仅初始化数据库管理器
+            ApplicationContext.initialize(db_manager=my_manager)
+            
+            # 初始化所有属性
+            ApplicationContext.initialize(
+                db_config=config,
+                db_manager=manager,
+                context=my_context
+            )
+        """
+        with cls._lock:
+            if db_config is not None and cls.db_config is None:
+                cls.db_config = db_config
+            if db_manager is not None and cls.db_manager is None:
+                cls.db_manager = db_manager
+            if project_name is not None and context is not None:
+                cls._contexts[project_name] = context    
+
+    @classmethod
+    def get_db_manager(cls) -> BaseDatabaseManager:
+        """获取数据库管理器实例
+        
+        返回:
+            BaseDatabaseManager: 已初始化的数据库管理器对象
+        
+        异常:
+            RuntimeError: 当db_manager尚未初始化（为None）时抛出
+        
+        示例:
+            db_manager = ApplicationContext.get_db_manager()
+            result = db_manager.query("SELECT * FROM users")
+        """
+        if cls.db_manager is None:
+            raise RuntimeError("Database manager not initialized")
+        return cls.db_manager
+    
+    @classmethod
+    def get_context(cls,project_name: str) -> ContextType:
+        """获取项目特定的上下文
+        
+        返回:
+            ContextType: 项目特定的上下文对象，类型由泛型参数决定
+        
+        异常:
+            RuntimeError: 当context尚未初始化（为None）时抛出
+        
+        示例:
+            ctx = ApplicationContext[MyContext].get_context()
+            print(ctx.user_id)  # 类型安全，IDE可提供代码补全
+        """
+        if cls._contexts is None:
+            raise RuntimeError("Context not initialized")
+        return cls._contexts[project_name]
+    
+    @classmethod
+    def reset(cls):
+        """重置全局上下文
+        
+        将所有的类属性（db_config, db_manager, context）重置为None。
+        使用线程锁保证重置操作的线程安全性。
+        
+        通常在以下场景使用:
+            - 单元测试的清理阶段，避免测试用例之间的状态污染
+            - 应用重新初始化前，需要清空旧的状态
+            - 切换不同的运行时环境
+        
+        示例:
+            # 测试用例清理
+            def tearDown(self):
+                ApplicationContext.reset()
+        """
+        with cls._lock:
+            cls.db_config = None
+            cls.db_manager = None
+            cls._contexts = None
+
+
+__all__ = ['ApplicationContext']

magic_base-0.1.2/src/magic_base/data_access/config/base_database_config.py

@@ -0,0 +1,353 @@
+"""
+数据库配置基类
+"""
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+from pathlib import Path
+from enum import Enum
+
+
+class DatabaseType(Enum):
+    """数据库类型枚举
+    
+    定义了支持的数据库类型，用于统一配置不同数据库的连接参数。
+    
+    成员:
+        SQLITE: SQLite 轻量级文件数据库
+        POSTGRESQL: PostgreSQL 关系型数据库
+        MYSQL: MySQL 关系型数据库
+    """
+    SQLITE = "sqlite"
+    POSTGRESQL = "postgresql"
+    MYSQL = "mysql"
+
+
+class BaseDatabaseConfig(ABC):
+    """数据库配置抽象基类
+    
+    定义了数据库配置的标准接口，所有具体数据库配置类都应继承此类。
+    提供获取连接字符串和引擎选项的核心方法。
+    """
+    
+    @abstractmethod
+    def get_connection_string(self) -> str:
+        """获取数据库连接字符串
+        
+        根据配置的数据库类型和参数，生成符合 SQLAlchemy 格式的连接字符串。
+        
+        返回:
+            str: 数据库连接字符串，格式如 "sqlite:///path/to/db.db" 或
+                "postgresql://user:pass@localhost:5432/dbname"
+        """
+        pass
+    
+    @abstractmethod
+    def get_engine_options(self) -> Dict[str, Any]:
+        """获取引擎选项
+        
+        返回 SQLAlchemy 引擎初始化时所需的参数字典，包括连接池配置、日志设置等。
+        
+        返回:
+            Dict[str, Any]: 引擎选项字典，可直接传递给 SQLAlchemy create_engine 函数
+        """
+        pass
+
+    @abstractmethod
+    def get_db_path(self) -> str:
+        """获取数据库文件路径(仅限于sqlite)
+        
+        返回 sqlite数据库文件路径。        
+        
+        """
+        pass
+
+
+class MagicDatabaseConfig(BaseDatabaseConfig):
+    """
+    Magic 系列统一数据库配置
+    
+    为 Magic 系列项目提供统一的数据库配置管理，支持 SQLite、PostgreSQL 和 MySQL。
+    自动处理数据库文件的目录创建、路径解析等细节。
+    
+    设计原则:
+        只做一件事：提供统一的数据库配置，不涉及业务逻辑。
+    
+    类属性:
+        MAGIC_DATA_DIR: Magic 默认数据存储目录，位于用户家目录下的 magic/data
+    """
+    
+    MAGIC_DATA_DIR = Path.home() / "magic" / "data"
+    """Magic 默认数据目录，路径为 ~/magic/data"""
+    
+    # 数据库路径
+    db_path = None
+    def __init__(
+        self, 
+        db_type: DatabaseType = DatabaseType.SQLITE,
+        **kwargs
+    ):
+        """
+        初始化数据库配置
+        
+        参数:
+            db_type: 数据库类型，默认为 SQLite。可选值见 DatabaseType 枚举
+            **kwargs: 连接参数，根据数据库类型不同而不同
+            
+        不同数据库类型支持的 kwargs 参数:
+            SQLite:
+                - path: 数据库文件路径（可选），默认为 "magic.db"
+                      可以是相对路径或绝对路径
+                - echo: 是否打印 SQL 日志（可选），默认为 False
+                - pool_size: 连接池大小（可选），默认为 10
+                - max_overflow: 连接池溢出限制（可选），默认为 20
+                - pool_pre_ping: 连接前检查（可选），默认为 True
+                - pool_recycle: 连接回收时间（秒，可选），默认为 3600
+                
+            PostgreSQL:
+                - host: 数据库主机地址（可选），默认为 "localhost"
+                - port: 数据库端口（可选），默认为 5432
+                - user: 数据库用户名（可选），默认为空字符串
+                - password: 数据库密码（可选），默认为空字符串
+                - database: 数据库名称（可选），默认为 "magic"
+                - echo: 是否打印 SQL 日志（可选），默认为 False
+                - pool_size: 连接池大小（可选），默认为 10
+                - max_overflow: 连接池溢出限制（可选），默认为 20
+                - pool_pre_ping: 连接前检查（可选），默认为 True
+                - pool_recycle: 连接回收时间（秒，可选），默认为 3600
+                
+            MySQL:
+                - host: 数据库主机地址（可选），默认为 "localhost"
+                - port: 数据库端口（可选），默认为 3306
+                - user: 数据库用户名（可选），默认为空字符串
+                - password: 数据库密码（可选），默认为空字符串
+                - database: 数据库名称（可选），默认为 "magic"
+                - echo: 是否打印 SQL 日志（可选），默认为 False
+                - pool_size: 连接池大小（可选），默认为 10
+                - max_overflow: 连接池溢出限制（可选），默认为 20
+                - pool_pre_ping: 连接前检查（可选），默认为 True
+                - pool_recycle: 连接回收时间（秒，可选），默认为 3600
+        
+        示例:
+            # 默认 SQLite 配置
+            config = MagicDatabaseConfig()
+            
+            # 自定义 SQLite 路径
+            config = MagicDatabaseConfig(
+                DatabaseType.SQLITE,
+                path="./myapp/custom.db",
+                echo=True
+            )
+            
+            # PostgreSQL 配置
+            config = MagicDatabaseConfig(
+                DatabaseType.POSTGRESQL,
+                host="localhost",
+                port=5432,
+                user="magic_user",
+                password="secure_pass",
+                database="magic_db"
+            )
+        """
+        self.db_type = db_type
+        """数据库类型"""
+        
+        self.kwargs = kwargs
+        """连接参数字典"""
+        
+        self._engine_options_cache = None
+        """引擎选项缓存，避免重复计算"""
+        
+        if db_type == DatabaseType.SQLITE:        
+            # 本地数据库路径，服务于 sqlite
+            self.db_path = self._get_sqlite_path()
+            """SQLite 数据库文件路径（仅 SQLite 类型有效）"""
+        else:
+            self.db_path = None
+    
+    def get_connection_string(self) -> str:
+        """统一构建连接字符串
+        
+        根据数据库类型调用对应的构建方法，返回符合 SQLAlchemy 格式的连接字符串。
+        
+        返回:
+            str: 数据库连接字符串
+            
+        异常:
+            ValueError: 当数据库类型不支持时抛出
+        """
+        if self.db_type == DatabaseType.SQLITE:
+            return self._build_sqlite()
+        elif self.db_type == DatabaseType.POSTGRESQL:
+            return self._build_postgresql()
+        elif self.db_type == DatabaseType.MYSQL:
+            return self._build_mysql()
+        else:
+            raise ValueError(f"Unsupported database type: {self.db_type}")
+    
+    def _get_sqlite_path(self) -> str:
+        """获取 SQLite 数据库路径
+        
+        处理 SQLite 数据库文件路径的逻辑：
+        1. 如果用户未指定 path 参数，使用默认文件名并放在 MAGIC_DATA_DIR 下
+        2. 如果用户指定了 path 参数：
+           - 绝对路径：直接使用
+           - 相对路径：相对于当前工作目录
+        3. 自动创建目标目录（如果不存在）
+        
+        返回:
+            str: SQLite 数据库文件的完整路径字符串
+        """
+        path = self.kwargs.get("path", "magic.db")
+        
+        # 判断是否使用默认目录
+        if "path" not in self.kwargs:
+            # 用户没有指定 path，使用默认目录
+            path = self.MAGIC_DATA_DIR / path
+            self.MAGIC_DATA_DIR.mkdir(parents=True, exist_ok=True)
+        else:
+            # 用户指定了 path，处理相对路径
+            path_obj = Path(path)
+            if not path_obj.is_absolute():
+                # 相对路径：相对于当前工作目录
+                path = Path.cwd() / path_obj
+            else:
+                path = path_obj
+            
+            # 确保目录存在
+            path.parent.mkdir(parents=True, exist_ok=True)
+        
+        return str(path)
+        
+    def _build_sqlite(self) -> str:
+        """构建 SQLite 连接字符串
+        
+        返回:
+            str: SQLite 连接字符串，格式如 "sqlite:///path/to/database.db"
+        """
+        return f"sqlite:///{self.db_path}"
+    
+    def _build_postgresql(self) -> str:
+        """构建 PostgreSQL 连接字符串
+        
+        返回:
+            str: PostgreSQL 连接字符串，格式如 "postgresql://user:pass@host:port/database"
+        """
+        host = self.kwargs.get("host", "localhost")
+        port = self.kwargs.get("port", 5432)
+        user = self.kwargs.get("user", "")
+        password = self.kwargs.get("password", "")
+        database = self.kwargs.get("database", "magic")
+        
+        auth = f"{user}:{password}@" if user and password else f"{user}@" if user else ""
+        return f"postgresql://{auth}{host}:{port}/{database}"
+    
+    def _build_mysql(self) -> str:
+        """构建 MySQL 连接字符串
+        
+        使用 PyMySQL 驱动，返回格式为 "mysql+pymysql://..."
+        
+        返回:
+            str: MySQL 连接字符串，格式如 "mysql+pymysql://user:pass@host:port/database"
+        """
+        host = self.kwargs.get("host", "localhost")
+        port = self.kwargs.get("port", 3306)
+        user = self.kwargs.get("user", "")
+        password = self.kwargs.get("password", "")
+        database = self.kwargs.get("database", "magic")
+        
+        auth = f"{user}:{password}@" if user and password else f"{user}@" if user else ""
+        return f"mysql+pymysql://{auth}{host}:{port}/{database}"
+    
+    def get_engine_options(self) -> Dict[str, Any]:
+        """获取引擎选项
+        
+        返回 SQLAlchemy 引擎初始化参数，包括连接池配置和日志设置。
+        结果会被缓存以提高性能。
+        
+        SQLite 特殊处理:
+            自动添加 connect_args = {"check_same_thread": False} 以支持多线程访问
+        
+        返回:
+            Dict[str, Any]: 引擎选项字典，包含以下配置：
+                - echo: 是否打印 SQL 日志
+                - pool_size: 连接池大小
+                - max_overflow: 连接池溢出限制
+                - pool_pre_ping: 连接前是否检查可用性
+                - pool_recycle: 连接回收时间（秒）
+                - connect_args: 连接参数（仅 SQLite）
+        """
+        if self._engine_options_cache:
+            return self._engine_options_cache
+        
+        # 默认选项
+        default_options = {
+            "echo": self.kwargs.get("echo", False),
+            "pool_size": self.kwargs.get("pool_size", 10),
+            "max_overflow": self.kwargs.get("max_overflow", 20),
+            "pool_pre_ping": self.kwargs.get("pool_pre_ping", True),
+            "pool_recycle": self.kwargs.get("pool_recycle", 3600),
+        }
+        
+        # SQLite 特殊配置
+        if self.db_type == DatabaseType.SQLITE:
+            default_options["connect_args"] = {"check_same_thread": False}
+        
+        self._engine_options_cache = default_options
+        return self._engine_options_cache
+    
+    def get_data_dir(self) -> Path:
+        """获取数据目录
+        
+        仅 SQLite 数据库支持此方法，返回默认数据存储目录。
+        
+        返回:
+            Path: Magic 默认数据目录路径对象
+            
+        异常:
+            RuntimeError: 当数据库类型不是 SQLite 时抛出
+        """
+        if self.db_type != DatabaseType.SQLITE:
+            raise RuntimeError("Data directory only available for SQLite")
+        return self.MAGIC_DATA_DIR
+    
+    def get_db_path(self) -> str:
+        """获取数据库文件路径
+        
+        返回:
+            str: 数据库文件的完整路径字符串（仅 SQLite 类型有效）
+        """
+        return self.db_path
+
+
+
+# 使用示例
+if __name__ == "__main__":
+    # 1. 默认 SQLite（最常用）
+    config = MagicDatabaseConfig()
+    print(config.get_connection_string())
+    # 输出: sqlite:///Users/xxx/magic/data/magic.db
+    
+    # 2. 自定义 SQLite
+    config = MagicDatabaseConfig(
+        DatabaseType.SQLITE,
+        path="./myapp.db",
+        echo=True
+    )
+    
+    # 3. PostgreSQL
+    config = MagicDatabaseConfig(
+        DatabaseType.POSTGRESQL,
+        host="localhost",
+        user="magic",
+        password="secret",
+        database="magic_db"
+    )
+    
+    # 4. MySQL
+    config = MagicDatabaseConfig(
+        DatabaseType.MYSQL,
+        host="192.168.1.100",
+        user="root",
+        password="pass123",
+        database="magic_prod"
+    )