db_client_toolkit 0.0.1__py3-none-any.whl

db_toolkit/core/__init__.py

@@ -0,0 +1,9 @@
+"""
+核心模块
+包含基类和抽象接口
+"""
+
+from .base import BaseClient
+from .sql_base import SQLBaseClient
+
+__all__ = ['BaseClient', 'SQLBaseClient']

db_toolkit/core/base.py

@@ -0,0 +1,194 @@
+"""
+数据库客户端抽象基类
+定义了所有数据库客户端必须实现的接口
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Union
+
+
+logger = logging.getLogger(__name__)
+
+
+class BaseClient(ABC):
+    """
+    数据库客户端抽象基类
+    
+    所有数据库客户端都应继承此类并实现抽象方法
+    """
+    
+    def __init__(self, config: Dict[str, Any]):
+        """
+        初始化数据库客户端
+        
+        Args:
+            config: 数据库配置字典
+        """
+        self.config = config
+        self.connection = None
+        self._connected = False
+        self._validate_config()
+    
+    def _validate_config(self) -> None:
+        """
+        验证配置参数
+        子类可以重写此方法以实现特定的配置验证
+        """
+        if not isinstance(self.config, dict):
+            raise ValueError("配置必须是字典类型")
+    
+    @abstractmethod
+    def connect(self) -> bool:
+        """
+        连接到数据库
+        
+        Returns:
+            bool: 连接是否成功
+            
+        Raises:
+            ConnectionError: 连接失败时抛出
+        """
+        pass
+    
+    @abstractmethod
+    def disconnect(self) -> bool:
+        """
+        断开数据库连接
+        
+        Returns:
+            bool: 断开是否成功
+        """
+        pass
+    
+    @abstractmethod
+    def is_connected(self) -> bool:
+        """
+        检查是否已连接
+        
+        Returns:
+            bool: 是否已连接
+        """
+        pass
+    
+    @abstractmethod
+    def execute(self, query: str, params: Optional[Union[tuple, dict]] = None) -> Any:
+        """
+        执行原生查询
+        
+        Args:
+            query: 查询语句
+            params: 查询参数
+            
+        Returns:
+            Any: 查询结果
+            
+        Raises:
+            QueryError: 查询执行失败时抛出
+        """
+        pass
+    
+    @abstractmethod
+    def insert(self, table: str, data: Dict[str, Any]) -> Any:
+        """
+        插入单条数据
+        
+        Args:
+            table: 表名或集合名
+            data: 要插入的数据
+            
+        Returns:
+            Any: 插入的记录ID或结果
+            
+        Raises:
+            QueryError: 插入失败时抛出
+        """
+        pass
+    
+    @abstractmethod
+    def update(self, table: str, data: Dict[str, Any], 
+               condition: Dict[str, Any]) -> int:
+        """
+        更新数据
+        
+        Args:
+            table: 表名或集合名
+            data: 要更新的数据
+            condition: 更新条件
+            
+        Returns:
+            int: 受影响的行数
+            
+        Raises:
+            QueryError: 更新失败时抛出
+        """
+        pass
+    
+    @abstractmethod
+    def delete(self, table: str, condition: Dict[str, Any]) -> int:
+        """
+        删除数据
+        
+        Args:
+            table: 表名或集合名
+            condition: 删除条件
+            
+        Returns:
+            int: 受影响的行数
+            
+        Raises:
+            QueryError: 删除失败时抛出
+        """
+        pass
+    
+    @abstractmethod
+    def select(self, table: str, 
+               fields: Optional[List[str]] = None,
+               condition: Optional[Dict[str, Any]] = None,
+               limit: Optional[int] = None,
+               offset: Optional[int] = None,
+               order_by: Optional[List[tuple]] = None) -> List[Dict]:
+        """
+        查询数据
+        
+        Args:
+            table: 表名或集合名
+            fields: 要查询的字段列表
+            condition: 查询条件
+            limit: 限制返回记录数
+            offset: 偏移量
+            order_by: 排序规则，格式为 [('field', 'ASC/DESC'), ...]
+            
+        Returns:
+            List[Dict]: 查询结果列表
+            
+        Raises:
+            QueryError: 查询失败时抛出
+        """
+        pass
+    
+    def ping(self) -> bool:
+        """
+        测试数据库连接
+        
+        Returns:
+            bool: 连接是否正常
+        """
+        try:
+            return self.is_connected()
+        except Exception:
+            return False
+    
+    def __enter__(self):
+        """上下文管理器入口"""
+        self.connect()
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """上下文管理器出口"""
+        self.disconnect()
+        return False
+    
+    def __repr__(self) -> str:
+        """返回对象的字符串表示"""
+        return f"<{self.__class__.__name__} connected={self._connected}>"

db_toolkit/core/sql_base.py

@@ -0,0 +1,163 @@
+"""
+SQL数据库客户端基类
+提供关系型数据库的通用功能
+"""
+
+from abc import abstractmethod
+from typing import Any, Dict, List, Optional
+
+from .base import BaseClient
+
+
+class SQLBaseClient(BaseClient):
+    """
+    SQL数据库客户端基类
+    为关系型数据库提供通用的SQL构建方法
+    """
+
+    @property
+    @abstractmethod
+    def placeholder(self) -> str:
+        """
+        SQL参数占位符
+        不同数据库使用不同的占位符：
+        - MySQL/PostgreSQL: %s
+        - SQLite: ?
+        
+        Returns:
+            str: 占位符字符
+        """
+        pass
+
+    def _build_insert_query(self, table: str, data: Dict[str, Any]) -> tuple:
+        """
+        构建INSERT查询
+        
+        Args:
+            table: 表名
+            data: 要插入的数据
+            
+        Returns:
+            tuple: (查询语句, 参数元组)
+        """
+        fields = ', '.join(data.keys())
+        placeholders = ', '.join([self.placeholder] * len(data))
+        query = f"INSERT INTO {table} ({fields}) VALUES ({placeholders})"
+        return query, tuple(data.values())
+
+    def _build_update_query(self, table: str, data: Dict[str, Any],
+                            condition: Dict[str, Any]) -> tuple:
+        """
+        构建UPDATE查询
+        
+        Args:
+            table: 表名
+            data: 要更新的数据
+            condition: 更新条件
+            
+        Returns:
+            tuple: (查询语句, 参数元组)
+        """
+        set_clause = ', '.join([f"{k} = {self.placeholder}" for k in data.keys()])
+        where_clause = ' AND '.join([f"{k} = {self.placeholder}" for k in condition.keys()])
+        query = f"UPDATE {table} SET {set_clause} WHERE {where_clause}"
+        params = tuple(data.values()) + tuple(condition.values())
+        return query, params
+
+    def _build_delete_query(self, table: str, condition: Dict[str, Any]) -> tuple:
+        """
+        构建DELETE查询
+        
+        Args:
+            table: 表名
+            condition: 删除条件
+            
+        Returns:
+            tuple: (查询语句, 参数元组)
+        """
+        where_clause = ' AND '.join([f"{k} = {self.placeholder}" for k in condition.keys()])
+        query = f"DELETE FROM {table} WHERE {where_clause}"
+        return query, tuple(condition.values())
+
+    def _build_select_query(self, table: str,
+                            fields: Optional[List[str]] = None,
+                            condition: Optional[Dict[str, Any]] = None,
+                            limit: Optional[int] = None,
+                            offset: Optional[int] = None,
+                            order_by: Optional[List[tuple]] = None) -> tuple:
+        """
+        构建SELECT查询
+        
+        Args:
+            table: 表名
+            fields: 字段列表
+            condition: 查询条件
+            limit: 限制数量
+            offset: 偏移量
+            order_by: 排序规则
+            
+        Returns:
+            tuple: (查询语句, 参数元组)
+        """
+        # SELECT子句
+        fields_str = ', '.join(fields) if fields else '*'
+        query = f"SELECT {fields_str} FROM {table}"
+        params = []
+
+        # WHERE子句
+        if condition:
+            where_clause = ' AND '.join([f"{k} = {self.placeholder}" for k in condition.keys()])
+            query += f" WHERE {where_clause}"
+            params.extend(condition.values())
+
+        # ORDER BY子句
+        if order_by:
+            order_parts = [f"{field} {direction}" for field, direction in order_by]
+            query += " ORDER BY " + ", ".join(order_parts)
+
+        # LIMIT子句
+        if limit is not None:
+            query += f" LIMIT {limit}"
+
+        # OFFSET子句
+        if offset is not None:
+            query += f" OFFSET {offset}"
+
+        return query, tuple(params)
+
+    def count(self, table: str, condition: Optional[Dict[str, Any]] = None) -> int:
+        """
+        计数查询
+        
+        Args:
+            table: 表名
+            condition: 查询条件
+            
+        Returns:
+            int: 记录数量
+        """
+        query = f"SELECT COUNT(*) as count FROM {table}"
+        params = ()
+
+        if condition:
+            where_clause = ' AND '.join([f"{k} = {self.placeholder}" for k in condition.keys()])
+            query += f" WHERE {where_clause}"
+            params = tuple(condition.values())
+
+        result = self.execute(query, params)
+        if result and len(result) > 0:
+            return result[0].get('count', 0)
+        return 0
+
+    def exists(self, table: str, condition: Dict[str, Any]) -> bool:
+        """
+        检查记录是否存在
+        
+        Args:
+            table: 表名
+            condition: 查询条件
+            
+        Returns:
+            bool: 是否存在
+        """
+        return self.count(table, condition) > 0

db_toolkit/exceptions/__init__.py

@@ -0,0 +1,38 @@
+"""
+数据库工具包的自定义异常
+"""
+
+
+class DatabaseError(Exception):
+    """数据库基础异常类"""
+    pass
+
+
+class ConnectionError(DatabaseError):
+    """连接异常"""
+    pass
+
+
+class QueryError(DatabaseError):
+    """查询执行异常"""
+    pass
+
+
+class ConfigurationError(DatabaseError):
+    """配置异常"""
+    pass
+
+
+class ValidationError(DatabaseError):
+    """数据验证异常"""
+    pass
+
+
+class NotSupportedError(DatabaseError):
+    """不支持的操作异常"""
+    pass
+
+
+class TransactionError(DatabaseError):
+    """事务异常"""
+    pass

db_toolkit/mixins/__init__.py

@@ -0,0 +1,12 @@
+"""
+混入模块
+提供可组合的功能扩展
+"""
+
+from .batch_ops import BatchOperationsMixin
+from .transaction import TransactionMixin
+
+__all__ = [
+    'BatchOperationsMixin',
+    'TransactionMixin',
+]

db_toolkit/mixins/batch_ops.py

@@ -0,0 +1,194 @@
+"""
+批量操作混入类
+为数据库客户端提供批量操作功能
+"""
+
+from typing import List, Dict, Any
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class BatchOperationsMixin:
+    """
+    批量操作混入类
+    
+    为数据库客户端添加批量插入、更新、删除功能
+    """
+
+    def batch_insert(self, table: str, data_list: List[Dict[str, Any]],
+                     chunk_size: int = 100) -> List[Any]:
+        """
+        批量插入数据
+        
+        Args:
+            table: 表名
+            data_list: 数据列表
+            chunk_size: 每批次大小
+            
+        Returns:
+            List[Any]: 插入结果列表
+            
+        Examples:
+            >>> data = [
+            ...     {'name': 'Alice', 'age': 25},
+            ...     {'name': 'Bob', 'age': 30}
+            ... ]
+            >>> results = client.batch_insert('users', data)
+        """
+        if not data_list:
+            logger.warning("批量插入数据列表为空")
+            return []
+
+        results = []
+        total = len(data_list)
+
+        # 分批处理
+        for i in range(0, total, chunk_size):
+            chunk = data_list[i:i + chunk_size]
+
+            for data in chunk:
+                try:
+                    result = self.insert(table, data)
+                    results.append(result)
+                except Exception as e:
+                    logger.error(f"批量插入失败: {e}")
+                    results.append(None)
+
+            logger.debug(f"批量插入进度: {min(i + chunk_size, total)}/{total}")
+
+        success_count = sum(1 for r in results if r is not None)
+        logger.info(f"批量插入完成: {success_count}/{total} 成功")
+
+        return results
+
+    def batch_update(self, table: str, updates: List[Dict[str, Any]],
+                     chunk_size: int = 100) -> int:
+        """
+        批量更新数据
+        
+        Args:
+            table: 表名
+            updates: 更新列表，每项包含 {'data': {...}, 'condition': {...}}
+            chunk_size: 每批次大小
+            
+        Returns:
+            int: 总共更新的行数
+            
+        Examples:
+            >>> updates = [
+            ...     {'data': {'age': 26}, 'condition': {'name': 'Alice'}},
+            ...     {'data': {'age': 31}, 'condition': {'name': 'Bob'}}
+            ... ]
+            >>> count = client.batch_update('users', updates)
+        """
+        if not updates:
+            logger.warning("批量更新列表为空")
+            return 0
+
+        total_count = 0
+        total = len(updates)
+
+        # 分批处理
+        for i in range(0, total, chunk_size):
+            chunk = updates[i:i + chunk_size]
+
+            for update_item in chunk:
+                try:
+                    data = update_item.get('data', {})
+                    condition = update_item.get('condition', {})
+
+                    if not data or not condition:
+                        logger.warning(f"更新项缺少data或condition: {update_item}")
+                        continue
+
+                    count = self.update(table, data, condition)
+                    total_count += count
+
+                except Exception as e:
+                    logger.error(f"批量更新失败: {e}")
+
+            logger.debug(f"批量更新进度: {min(i + chunk_size, total)}/{total}")
+
+        logger.info(f"批量更新完成: {total_count} 条记录")
+        return total_count
+
+    def batch_delete(self, table: str, conditions: List[Dict[str, Any]],
+                     chunk_size: int = 100) -> int:
+        """
+        批量删除数据
+        
+        Args:
+            table: 表名
+            conditions: 删除条件列表
+            chunk_size: 每批次大小
+            
+        Returns:
+            int: 总共删除的行数
+            
+        Examples:
+            >>> conditions = [
+            ...     {'name': 'Alice'},
+            ...     {'name': 'Bob'}
+            ... ]
+            >>> count = client.batch_delete('users', conditions)
+        """
+        if not conditions:
+            logger.warning("批量删除条件列表为空")
+            return 0
+
+        total_count = 0
+        total = len(conditions)
+
+        # 分批处理
+        for i in range(0, total, chunk_size):
+            chunk = conditions[i:i + chunk_size]
+
+            for condition in chunk:
+                try:
+                    count = self.delete(table, condition)
+                    total_count += count
+                except Exception as e:
+                    logger.error(f"批量删除失败: {e}")
+
+            logger.debug(f"批量删除进度: {min(i + chunk_size, total)}/{total}")
+
+        logger.info(f"批量删除完成: {total_count} 条记录")
+        return total_count
+
+    def upsert(self, table: str, data: Dict[str, Any],
+               unique_fields: List[str]) -> Any:
+        """
+        插入或更新（如果存在则更新，否则插入）
+        
+        Args:
+            table: 表名
+            data: 数据
+            unique_fields: 用于判断唯一性的字段
+            
+        Returns:
+            插入或更新结果
+            
+        Examples:
+            >>> data = {'email': 'user@example.com', 'name': 'Alice', 'age': 25}
+            >>> client.upsert('users', data, ['email'])
+        """
+        # 构建查询条件
+        condition = {field: data[field] for field in unique_fields if field in data}
+
+        if not condition:
+            logger.warning("upsert条件为空，执行插入操作")
+            return self.insert(table, data)
+
+        # 检查记录是否存在
+        existing = self.select(table, condition=condition, limit=1)
+
+        if existing:
+            # 更新
+            logger.debug(f"记录已存在，执行更新: {condition}")
+            self.update(table, data, condition)
+            return condition
+        else:
+            # 插入
+            logger.debug(f"记录不存在，执行插入: {condition}")
+            return self.insert(table, data)