db_client_toolkit 0.0.1__py3-none-any.whl

db_toolkit/mixins/transaction.py

@@ -0,0 +1,206 @@
+"""
+事务混入类
+为支持事务的数据库客户端提供事务管理功能
+"""
+
+import logging
+from contextlib import contextmanager
+
+from ..exceptions import TransactionError
+
+
+logger = logging.getLogger(__name__)
+
+
+class TransactionMixin:
+    """
+    事务混入类
+    
+    为数据库客户端添加事务管理功能
+    注意：仅适用于支持事务的数据库（如MySQL, PostgreSQL, SQLite）
+    """
+    
+    def begin(self) -> None:
+        """
+        开始事务
+        
+        Raises:
+            TransactionError: 开始事务失败时
+        """
+        if not hasattr(self, 'connection') or not self.connection:
+            raise TransactionError("数据库未连接")
+        
+        try:
+            # 不同数据库的事务开始方式
+            if hasattr(self.connection, 'begin'):
+                self.connection.begin()
+            elif hasattr(self.connection, 'autocommit'):
+                self.connection.autocommit = False
+            else:
+                # 对于不显式支持begin的数据库，通常自动开始事务
+                pass
+            
+            logger.debug("事务已开始")
+            
+        except Exception as e:
+            logger.error(f"开始事务失败: {e}")
+            raise TransactionError(f"开始事务失败: {e}")
+    
+    def commit(self) -> None:
+        """
+        提交事务
+        
+        Raises:
+            TransactionError: 提交事务失败时
+        """
+        if not hasattr(self, 'connection') or not self.connection:
+            raise TransactionError("数据库未连接")
+        
+        try:
+            if hasattr(self.connection, 'commit'):
+                self.connection.commit()
+                logger.debug("事务已提交")
+            else:
+                logger.warning("数据库不支持事务提交")
+                
+        except Exception as e:
+            logger.error(f"提交事务失败: {e}")
+            raise TransactionError(f"提交事务失败: {e}")
+    
+    def rollback(self) -> None:
+        """
+        回滚事务
+        
+        Raises:
+            TransactionError: 回滚事务失败时
+        """
+        if not hasattr(self, 'connection') or not self.connection:
+            raise TransactionError("数据库未连接")
+        
+        try:
+            if hasattr(self.connection, 'rollback'):
+                self.connection.rollback()
+                logger.debug("事务已回滚")
+            else:
+                logger.warning("数据库不支持事务回滚")
+                
+        except Exception as e:
+            logger.error(f"回滚事务失败: {e}")
+            raise TransactionError(f"回滚事务失败: {e}")
+    
+    @contextmanager
+    def transaction(self):
+        """
+        事务上下文管理器
+        
+        Yields:
+            self: 数据库客户端实例
+            
+        Examples:
+            >>> with client.transaction():
+            ...     client.insert('users', {'name': 'Alice'})
+            ...     client.insert('users', {'name': 'Bob'})
+            # 如果没有异常，自动提交；如果有异常，自动回滚
+        """
+        try:
+            self.begin()
+            yield self
+            self.commit()
+            logger.info("事务成功提交")
+            
+        except Exception as e:
+            self.rollback()
+            logger.error(f"事务回滚: {e}")
+            raise
+    
+    def execute_in_transaction(self, *operations):
+        """
+        在事务中执行多个操作
+        
+        Args:
+            *operations: 操作函数列表，每个函数接收client作为参数
+            
+        Returns:
+            执行结果列表
+            
+        Examples:
+            >>> def op1(client):
+            ...     return client.insert('users', {'name': 'Alice'})
+            >>> def op2(client):
+            ...     return client.insert('users', {'name': 'Bob'})
+            >>> results = client.execute_in_transaction(op1, op2)
+        """
+        results = []
+        
+        try:
+            self.begin()
+            
+            for operation in operations:
+                if callable(operation):
+                    result = operation(self)
+                    results.append(result)
+                else:
+                    logger.warning(f"跳过非可调用对象: {operation}")
+            
+            self.commit()
+            logger.info(f"事务成功完成 {len(results)} 个操作")
+            return results
+            
+        except Exception as e:
+            self.rollback()
+            logger.error(f"事务执行失败: {e}")
+            raise TransactionError(f"事务执行失败: {e}")
+    
+    def savepoint(self, name: str) -> None:
+        """
+        创建保存点
+        
+        Args:
+            name: 保存点名称
+            
+        Note:
+            仅PostgreSQL和部分数据库支持保存点
+        """
+        try:
+            if hasattr(self, 'execute'):
+                self.execute(f"SAVEPOINT {name}")
+                logger.debug(f"创建保存点: {name}")
+            else:
+                logger.warning("数据库不支持保存点")
+        except Exception as e:
+            logger.error(f"创建保存点失败: {e}")
+            raise TransactionError(f"创建保存点失败: {e}")
+    
+    def rollback_to_savepoint(self, name: str) -> None:
+        """
+        回滚到保存点
+        
+        Args:
+            name: 保存点名称
+        """
+        try:
+            if hasattr(self, 'execute'):
+                self.execute(f"ROLLBACK TO SAVEPOINT {name}")
+                logger.debug(f"回滚到保存点: {name}")
+            else:
+                logger.warning("数据库不支持保存点")
+        except Exception as e:
+            logger.error(f"回滚到保存点失败: {e}")
+            raise TransactionError(f"回滚到保存点失败: {e}")
+    
+    def release_savepoint(self, name: str) -> None:
+        """
+        释放保存点
+        
+        Args:
+            name: 保存点名称
+        """
+        try:
+            if hasattr(self, 'execute'):
+                self.execute(f"RELEASE SAVEPOINT {name}")
+                logger.debug(f"释放保存点: {name}")
+            else:
+                logger.warning("数据库不支持保存点")
+        except Exception as e:
+            logger.error(f"释放保存点失败: {e}")
+            raise TransactionError(f"释放保存点失败: {e}")

db_toolkit/utils/__init__.py

@@ -0,0 +1,15 @@
+"""
+工具模块
+包含工厂、配置管理器和查询构建器
+"""
+
+from .factory import ClientFactory, create_client
+from .config import ConfigManager
+from .query_builder import QueryBuilder
+
+__all__ = [
+    'ClientFactory',
+    'create_client',
+    'ConfigManager',
+    'QueryBuilder',
+]

db_toolkit/utils/config.py

@@ -0,0 +1,252 @@
+"""
+配置管理器
+用于管理数据库配置文件
+"""
+
+import json
+import os
+from typing import Dict, Any, Optional
+import logging
+
+from ..core.base import BaseClient
+from .factory import ClientFactory
+from ..exceptions import ConfigurationError
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigManager:
+    """
+    数据库配置管理器
+    
+    管理JSON格式的数据库配置文件，支持多个数据库配置
+    """
+    
+    def __init__(self, config_file: str = 'db_config.json'):
+        """
+        初始化配置管理器
+        
+        Args:
+            config_file: 配置文件路径
+        """
+        self.config_file = config_file
+        self.configs: Dict[str, Any] = self._load_config()
+    
+    def _load_config(self) -> Dict[str, Any]:
+        """
+        加载配置文件
+        
+        Returns:
+            Dict: 配置字典
+        """
+        if not os.path.exists(self.config_file):
+            logger.warning(f"配置文件不存在: {self.config_file}，使用空配置")
+            return {'databases': {}, 'default': None}
+        
+        try:
+            with open(self.config_file, 'r', encoding='utf-8') as f:
+                config = json.load(f)
+                logger.info(f"加载配置文件成功: {self.config_file}")
+                return config
+        except json.JSONDecodeError as e:
+            logger.error(f"配置文件JSON格式错误: {e}")
+            raise ConfigurationError(f"配置文件格式错误: {e}")
+        except Exception as e:
+            logger.error(f"加载配置文件失败: {e}")
+            raise ConfigurationError(f"加载配置文件失败: {e}")
+    
+    def _save_config(self) -> None:
+        """保存配置文件"""
+        try:
+            with open(self.config_file, 'w', encoding='utf-8') as f:
+                json.dump(self.configs, f, indent=2, ensure_ascii=False)
+            logger.info(f"保存配置文件成功: {self.config_file}")
+        except Exception as e:
+            logger.error(f"保存配置文件失败: {e}")
+            raise ConfigurationError(f"保存配置文件失败: {e}")
+    
+    def get_client(self, name: Optional[str] = None, auto_connect: bool = True) -> BaseClient:
+        """
+        获取数据库客户端
+        
+        Args:
+            name: 数据库配置名称，None则使用默认配置
+            auto_connect: 是否自动连接
+            
+        Returns:
+            BaseClient: 数据库客户端实例
+            
+        Raises:
+            ConfigurationError: 配置不存在或无效时
+            
+        Examples:
+            >>> manager = ConfigManager()
+            >>> with manager.get_client('mysql_prod') as client:
+            ...     users = client.select('users')
+        """
+        if name is None:
+            name = self.configs.get('default')
+            if not name:
+                raise ConfigurationError("未指定数据库名称且没有默认配置")
+        
+        db_config = self.configs.get('databases', {}).get(name)
+        if not db_config:
+            available = ', '.join(self.configs.get('databases', {}).keys())
+            raise ConfigurationError(
+                f"数据库配置不存在: '{name}'\n"
+                f"可用配置: {available or '(无)'}"
+            )
+        
+        db_type = db_config.get('type')
+        config = db_config.get('config', {})
+        
+        if not db_type:
+            raise ConfigurationError(f"数据库配置'{name}'缺少type字段")
+        
+        client = ClientFactory.create(db_type, config)
+        
+        if auto_connect:
+            client.connect()
+        
+        return client
+    
+    def add(self, name: str, db_type: str, config: Dict[str, Any], 
+            set_as_default: bool = False) -> None:
+        """
+        添加数据库配置
+        
+        Args:
+            name: 配置名称
+            db_type: 数据库类型
+            config: 数据库配置
+            set_as_default: 是否设置为默认配置
+            
+        Examples:
+            >>> manager = ConfigManager()
+            >>> manager.add('prod_db', 'mysql', {
+            ...     'host': 'localhost',
+            ...     'user': 'root',
+            ...     'password': 'pass',
+            ...     'database': 'prod'
+            ... })
+        """
+        if 'databases' not in self.configs:
+            self.configs['databases'] = {}
+        
+        self.configs['databases'][name] = {
+            'type': db_type,
+            'config': config
+        }
+        
+        if set_as_default or not self.configs.get('default'):
+            self.configs['default'] = name
+        
+        self._save_config()
+        logger.info(f"添加数据库配置: {name} ({db_type})")
+    
+    def remove(self, name: str) -> bool:
+        """
+        删除数据库配置
+        
+        Args:
+            name: 配置名称
+            
+        Returns:
+            bool: 是否删除成功
+        """
+        if name not in self.configs.get('databases', {}):
+            logger.warning(f"配置不存在: {name}")
+            return False
+        
+        del self.configs['databases'][name]
+        
+        # 如果删除的是默认配置，清除默认设置
+        if self.configs.get('default') == name:
+            self.configs['default'] = None
+        
+        self._save_config()
+        logger.info(f"删除数据库配置: {name}")
+        return True
+    
+    def set_default(self, name: str) -> None:
+        """
+        设置默认数据库
+        
+        Args:
+            name: 配置名称
+            
+        Raises:
+            ConfigurationError: 配置不存在时
+        """
+        if name not in self.configs.get('databases', {}):
+            raise ConfigurationError(f"配置不存在: {name}")
+        
+        self.configs['default'] = name
+        self._save_config()
+        logger.info(f"设置默认数据库: {name}")
+    
+    def list(self) -> Dict[str, str]:
+        """
+        列出所有配置
+        
+        Returns:
+            Dict[str, str]: 配置名称到数据库类型的映射
+        """
+        databases = self.configs.get('databases', {})
+        return {name: conf['type'] for name, conf in databases.items()}
+    
+    def get_default(self) -> Optional[str]:
+        """
+        获取默认配置名称
+        
+        Returns:
+            Optional[str]: 默认配置名称
+        """
+        return self.configs.get('default')
+    
+    def export_config(self, output_file: str) -> None:
+        """
+        导出配置到文件
+        
+        Args:
+            output_file: 输出文件路径
+        """
+        try:
+            with open(output_file, 'w', encoding='utf-8') as f:
+                json.dump(self.configs, f, indent=2, ensure_ascii=False)
+            logger.info(f"导出配置到: {output_file}")
+        except Exception as e:
+            logger.error(f"导出配置失败: {e}")
+            raise ConfigurationError(f"导出配置失败: {e}")
+    
+    def import_config(self, input_file: str, merge: bool = True) -> None:
+        """
+        从文件导入配置
+        
+        Args:
+            input_file: 输入文件路径
+            merge: 是否合并到现有配置（False则覆盖）
+        """
+        try:
+            with open(input_file, 'r', encoding='utf-8') as f:
+                imported = json.load(f)
+            
+            if merge:
+                # 合并数据库配置
+                if 'databases' in imported:
+                    if 'databases' not in self.configs:
+                        self.configs['databases'] = {}
+                    self.configs['databases'].update(imported['databases'])
+                
+                # 如果没有默认配置，使用导入的默认配置
+                if 'default' in imported and not self.configs.get('default'):
+                    self.configs['default'] = imported['default']
+            else:
+                self.configs = imported
+            
+            self._save_config()
+            logger.info(f"导入配置从: {input_file}")
+            
+        except Exception as e:
+            logger.error(f"导入配置失败: {e}")
+            raise ConfigurationError(f"导入配置失败: {e}")

db_toolkit/utils/factory.py

@@ -0,0 +1,172 @@
+"""
+数据库客户端工厂
+用于创建和管理数据库客户端实例
+"""
+
+from typing import Dict, Any, Type
+import logging
+
+from ..core.base import BaseClient
+from ..clients import (
+    MySQLClient,
+    PostgreSQLClient,
+    SQLiteClient,
+    MongoDBClient,
+    RedisClient,
+    SupabaseClient,
+)
+from ..exceptions import ConfigurationError
+
+
+logger = logging.getLogger(__name__)
+
+
+class ClientFactory:
+    """
+    数据库客户端工厂类
+    
+    负责创建和注册数据库客户端
+    """
+    
+    # 内置客户端注册表
+    _clients: Dict[str, Type[BaseClient]] = {
+        'mysql': MySQLClient,
+        'postgresql': PostgreSQLClient,
+        'postgres': PostgreSQLClient,  # 别名
+        'sqlite': SQLiteClient,
+        'sqlite3': SQLiteClient,  # 别名
+        'mongodb': MongoDBClient,
+        'mongo': MongoDBClient,  # 别名
+        'redis': RedisClient,
+        'supabase': SupabaseClient,
+    }
+    
+    @classmethod
+    def create(cls, db_type: str, config: Dict[str, Any]) -> BaseClient:
+        """
+        创建数据库客户端
+        
+        Args:
+            db_type: 数据库类型 (mysql, postgresql, sqlite, mongodb, redis, supabase)
+            config: 数据库配置字典
+            
+        Returns:
+            BaseClient: 数据库客户端实例
+            
+        Raises:
+            ConfigurationError: 当数据库类型不支持或配置无效时
+            
+        Examples:
+            >>> config = {'host': 'localhost', 'user': 'root', 'password': 'pass', 'database': 'test'}
+            >>> client = ClientFactory.create('mysql', config)
+        """
+        db_type = db_type.lower().strip()
+        
+        if db_type not in cls._clients:
+            available = ', '.join(sorted(set(cls._clients.keys())))
+            raise ConfigurationError(
+                f"不支持的数据库类型: '{db_type}'\n"
+                f"支持的类型: {available}"
+            )
+        
+        client_class = cls._clients[db_type]
+        
+        try:
+            logger.info(f"创建数据库客户端: {db_type}")
+            return client_class(config)
+        except Exception as e:
+            logger.error(f"创建数据库客户端失败: {e}")
+            raise ConfigurationError(f"创建数据库客户端失败: {e}")
+    
+    @classmethod
+    def register(cls, db_type: str, client_class: Type[BaseClient]) -> None:
+        """
+        注册自定义数据库客户端
+        
+        Args:
+            db_type: 数据库类型标识符
+            client_class: 客户端类（必须继承BaseClient）
+            
+        Raises:
+            ValueError: 当client_class不是BaseClient的子类时
+            
+        Examples:
+            >>> class CustomClient(BaseClient):
+            ...     pass
+            >>> ClientFactory.register('custom', CustomClient)
+        """
+        if not issubclass(client_class, BaseClient):
+            raise ValueError(f"{client_class.__name__} 必须继承 BaseClient")
+        
+        db_type = db_type.lower().strip()
+        cls._clients[db_type] = client_class
+        logger.info(f"注册自定义数据库客户端: {db_type} -> {client_class.__name__}")
+    
+    @classmethod
+    def unregister(cls, db_type: str) -> bool:
+        """
+        注销数据库客户端
+        
+        Args:
+            db_type: 数据库类型标识符
+            
+        Returns:
+            bool: 是否成功注销
+        """
+        db_type = db_type.lower().strip()
+        if db_type in cls._clients:
+            del cls._clients[db_type]
+            logger.info(f"注销数据库客户端: {db_type}")
+            return True
+        return False
+    
+    @classmethod
+    def list_available(cls) -> list:
+        """
+        列出所有可用的数据库类型
+        
+        Returns:
+            list: 数据库类型列表
+        """
+        return sorted(set(cls._clients.keys()))
+    
+    @classmethod
+    def get_client_class(cls, db_type: str) -> Type[BaseClient]:
+        """
+        获取数据库客户端类
+        
+        Args:
+            db_type: 数据库类型
+            
+        Returns:
+            Type[BaseClient]: 客户端类
+            
+        Raises:
+            ConfigurationError: 当数据库类型不存在时
+        """
+        db_type = db_type.lower().strip()
+        if db_type not in cls._clients:
+            raise ConfigurationError(f"数据库类型不存在: {db_type}")
+        return cls._clients[db_type]
+
+
+# 便捷函数
+def create_client(db_type: str, config: Dict[str, Any]) -> BaseClient:
+    """
+    创建数据库客户端的便捷函数
+    
+    Args:
+        db_type: 数据库类型
+        config: 配置字典
+        
+    Returns:
+        BaseClient: 数据库客户端实例
+        
+    Examples:
+        >>> from db_toolkit import create_client
+        >>> config = {'database': 'test.db'}
+        >>> client = create_client('sqlite', config)
+        >>> with client:
+        ...     results = client.select('users')
+    """
+    return ClientFactory.create(db_type, config)