mdbq 4.1.10__tar.gz → 4.1.12__tar.gz

{mdbq-4.1.10 → mdbq-4.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: mdbq
-Version: 4.1.10
+Version: 4.1.12
 Home-page: https://pypi.org/project/mdbq
 Author: xigua, 
 Author-email: 2587125111@qq.com

mdbq-4.1.12/mdbq/__version__.py

@@ -0,0 +1 @@
+VERSION = '4.1.12'

{mdbq-4.1.10 → mdbq-4.1.12}/mdbq/mysql/uploader.py

@@ -111,6 +111,7 @@ class MySQLUploader:
         :param read_timeout: 读取超时(秒)，默认为30
         :param write_timeout: 写入超时(秒)，默认为30
         :param ssl: SSL配置字典，默认为None
+        :param auto_creat_missing_cols: 自动添加缺失列，默认为False，建议手动维护表结构
         """
         self.username = username
         self.password = password
@@ -134,6 +135,7 @@ class MySQLUploader:
         self._table_metadata_cache = {}
         self.metadata_cache_ttl = 300  # 5分钟缓存时间
         self.pool = self._create_connection_pool()  # 创建连接池
+        self.auto_creat_missing_cols = False  # 自动添加缺失列，正常不要自动添加，建议手动维护表结构
 
     def _create_connection_pool(self) -> PooledDB:
         """
@@ -695,15 +697,16 @@ class MySQLUploader:
                 break
         
         if not allow_null:
-            logger.warning("该列不允许为空值", {
-                "库": db_name, 
-                "表": table_name, 
-                "allow_null": allow_null, 
-                "列": col_name, 
-                "值": original_value, 
-                "兜底值": fallback
-            })
-            return fallback  # 直接返回兜底值，而不是抛出异常
+            # 注释掉，这里可能会产生大量日志
+            # logger.debug("该列不允许为空值", {
+            #     "库": db_name, 
+            #     "表": table_name, 
+            #     "allow_null": allow_null, 
+            #     "列": col_name, 
+            #     "值": original_value, 
+            #     "兜底值": fallback
+            # })
+            return fallback  # 直接返回兜底值
         
         return None  # 允许空值时返回None
 
@@ -799,7 +802,13 @@ class MySQLUploader:
         
         # 统一处理空值
         if is_empty_value:
-            return self._get_fallback_value(column_type_lower, allow_null, db_name, table_name, col_name, value)
+            fallback_value = self._get_fallback_value(column_type_lower, allow_null, db_name, table_name, col_name, value)
+            # 如果返回了兜底值（非None），直接返回，不再进行后续验证
+            # 因为兜底值已经是根据列类型设计的合适值
+            if fallback_value is not None:
+                return fallback_value
+            # 如果返回None（允许空值的情况），继续后续处理
+            return None
         
         # JSON类型验证和转换
         if 'json' in column_type_lower:
@@ -1072,14 +1081,41 @@ class MySQLUploader:
                 '列': self._shorten_for_log(table_columns),
             })
             raise ValueError(f"获取列失败 `{db_name}`.`{table_name}`")
-        for col in set_typ:
-            if col not in table_columns:
-                logger.error('列不存在', {
+        # 检查并自动添加缺失的列
+        missing_columns = [col for col in set_typ if col not in table_columns]
+        if missing_columns:
+            if not self.auto_creat_missing_cols:
+                logger.error('列不存在且不支持自动添加，请手动维护表结构，并补齐缺失列', {
                     '库': db_name,
                     '表': table_name,
-                    '列': col,
+                    '缺失列数': len(missing_columns),
+                    '缺失列': missing_columns,
                 })
-                raise ValueError(f"列不存在: `{col}` -> `{db_name}`.`{table_name}`")
+                raise ValueError(f"列不存在: `{missing_columns}` -> `{db_name}`.`{table_name}`")
+            else:
+                # 表有缺失列时报错，建议不允许自动添加，手动检查数据一致性，以免产生不必要的表错误
+                # 自动添加缺失的列
+                for col in missing_columns:
+                    try:
+                        self._add_column_to_table(db_name, table_name, col, set_typ[col], allow_null)
+                        logger.info('自动添加缺失列', {
+                            '库': db_name,
+                            '表': table_name,
+                            '列': col,
+                            '类型': set_typ[col]
+                        })
+                    except Exception as e:
+                        logger.error('添加列失败', {
+                            '库': db_name,
+                            '表': table_name,
+                            '列': col,
+                            '类型': set_typ[col],
+                            '错误': str(e)
+                        })
+                        raise ValueError(f"添加列失败: `{col}` -> `{db_name}`.`{table_name}`: {str(e)}")
+                
+                # 重新获取表列信息
+                table_columns = self._get_table_columns(db_name, table_name)
         if date_column and date_column in table_columns:
             try:
                 self._ensure_index(db_name, table_name, date_column)
@@ -1183,12 +1219,17 @@ class MySQLUploader:
             set_typ: Dict[str, str],
             allow_null: bool = False,
             db_name: str = None, 
-            table_name: str = None, 
+            table_name: str = None,
+            auto_timestamps: bool = False
     ) -> Tuple[List[Dict], Dict[str, str]]:
         """
         准备要上传的数据，验证并转换数据类型
         根据set_typ自动处理所有数据类型的列：补齐缺失的列并丢弃多余的列
         """
+        # 处理自动时间戳功能
+        if auto_timestamps:
+            data, set_typ = self._process_auto_timestamps(data, set_typ, db_name, table_name)
+        
         # set_typ的键清洗
         if not set_typ:
             set_typ = {}
@@ -1300,21 +1341,67 @@ class MySQLUploader:
                         prepared_row[col_name] = self._validate_value(None, filtered_set_typ[col_name], allow_null, db_name, table_name, col_name)
                     except ValueError as e:
                         if not allow_null:
-                            error_msg = f"行号:{row_idx} -> 缺失列: `{col_name}`, 且不允许空值"
-                            logger.error(error_msg, {'row': self._shorten_for_log(row)})
-                            raise ValueError(error_msg)
-                        prepared_row[col_name] = None
+                            # 如果不允许空值但验证失败，尝试使用兜底值
+                            try:
+                                fallback_value = self._get_fallback_value(filtered_set_typ[col_name].lower(), allow_null, db_name, table_name, col_name, None)
+                                if fallback_value is not None:
+                                    prepared_row[col_name] = fallback_value
+                                    logger.warning(f"行号:{row_idx} -> 缺失列: `{col_name}`, 使用兜底值: {fallback_value}", {'row': self._shorten_for_log(row)})
+                                else:
+                                    error_msg = f"行号:{row_idx} -> 缺失列: `{col_name}`, 且不允许空值"
+                                    logger.error(error_msg, {'row': self._shorten_for_log(row)})
+                                    raise ValueError(error_msg)
+                            except Exception:
+                                error_msg = f"行号:{row_idx} -> 缺失列: `{col_name}`, 且不允许空值"
+                                logger.error(error_msg, {'row': self._shorten_for_log(row)})
+                                raise ValueError(error_msg)
+                        else:
+                            prepared_row[col_name] = None
                 else:
                     try:
                         prepared_row[col_name] = self._validate_value(row[col_name], filtered_set_typ[col_name], allow_null, db_name, table_name, col_name)
                     except ValueError as e:
-                        logger.error('数据验证失败', {
-                            '列': col_name,
-                            '行': row_idx,
-                            '报错': str(e),
-                            'row': self._shorten_for_log(row),
-                        })
-                        raise ValueError(f"行:{row_idx}, 列:`{col_name}`-> 报错: {str(e)}")
+                        # 如果数据验证失败，检查是否为空值且不允许空值，尝试使用兜底值
+                        original_value = row[col_name]
+                        is_empty_original = (original_value is None or 
+                                           original_value == '' or 
+                                           (not isinstance(original_value, (list, dict)) and 
+                                            pd.isna(original_value) if hasattr(pd, 'isna') else False))
+                        
+                        if is_empty_original and not allow_null:
+                            try:
+                                fallback_value = self._get_fallback_value(filtered_set_typ[col_name].lower(), allow_null, db_name, table_name, col_name, original_value)
+                                if fallback_value is not None:
+                                    prepared_row[col_name] = fallback_value
+                                    logger.warning(f"行:{row_idx}, 列:`{col_name}` -> 原值验证失败，使用兜底值: {fallback_value}", {
+                                        '原值': original_value,
+                                        '兜底值': fallback_value,
+                                        'row': self._shorten_for_log(row)
+                                    })
+                                else:
+                                    logger.error('数据验证失败', {
+                                        '列': col_name,
+                                        '行': row_idx,
+                                        '报错': str(e),
+                                        'row': self._shorten_for_log(row),
+                                    })
+                                    raise ValueError(f"行:{row_idx}, 列:`{col_name}`-> 报错: {str(e)}")
+                            except Exception:
+                                logger.error('数据验证失败', {
+                                    '列': col_name,
+                                    '行': row_idx,
+                                    '报错': str(e),
+                                    'row': self._shorten_for_log(row),
+                                })
+                                raise ValueError(f"行:{row_idx}, 列:`{col_name}`-> 报错: {str(e)}")
+                        else:
+                            logger.error('数据验证失败', {
+                                '列': col_name,
+                                '行': row_idx,
+                                '报错': str(e),
+                                'row': self._shorten_for_log(row),
+                            })
+                            raise ValueError(f"行:{row_idx}, 列:`{col_name}`-> 报错: {str(e)}")
             prepared_data.append(prepared_row)
         return prepared_data, filtered_set_typ
 
@@ -1334,7 +1421,8 @@ class MySQLUploader:
             indexes: Optional[List[str]] = None,
             update_on_duplicate: bool = False,
             transaction_mode: str = "batch",
-            unique_keys: Optional[List[List[str]]] = None
+            unique_keys: Optional[List[List[str]]] = None,
+            auto_timestamps: bool = False
     ):
         """
         上传数据到数据库的主入口方法
@@ -1357,6 +1445,7 @@ class MySQLUploader:
             - 'batch'   : 整批提交事务（性能最优）
             - 'hybrid'  : 混合模式（每N行提交，平衡性能与安全性）
         :param unique_keys: 唯一约束列表，每个元素为列名列表，支持多列组合唯一约束。格式：[['col1', 'col2'], ['col3']] 或 None
+        :param auto_timestamps: 是否自动添加创建时间和更新时间列，默认为False。启用后会自动添加'创建时间'和'更新时间'两列
         :raises: 可能抛出各种验证和数据库相关异常
 
         ---
@@ -1401,6 +1490,17 @@ class MySQLUploader:
         - 只要 update_on_duplicate=True 且表存在唯一约束（如 unique_keys），无论 check_duplicate 是否为 True，都会更新旧数据（即 ON DUPLICATE KEY UPDATE 生效）。
         - 如需"覆盖"行为，务必设置 update_on_duplicate=True，不管 check_duplicate 是否为 True。
         - 如需"跳过"行为，设置 update_on_duplicate=False 即可。
+
+        ---
+        auto_timestamps 参数：
+
+        - 当 auto_timestamps=True 时，系统会自动添加'创建时间'和'更新时间'两列
+        - 如果原始数据中已存在这两列，系统会先移除原始数据中的这些列，然后添加新的时间戳
+        - '创建时间'：记录数据首次插入的时间，使用当前时间戳
+        - '更新时间'：记录数据最后更新的时间，插入时与创建时间相同，更新时会自动更新为当前时间
+        - 时间戳列的数据类型为 DATETIME，格式为 'YYYY-MM-DD HH:MM:SS'
+        - 这两列会自动添加到 set_typ 中，无需手动指定
+        - 建议在需要审计数据变更历史的表中启用此功能
         """
         # upload_start = time.time()
         # 检查data参数是否为None
@@ -1410,7 +1510,7 @@ class MySQLUploader:
                 '表': table_name,
             })
             raise ValueError("data参数不能为None，请传入有效的数据")
-            
+        
         if isinstance(data, list) or (hasattr(data, 'shape') and hasattr(data, '__len__')):
             initial_row_count = len(data)
         else:
@@ -1471,7 +1571,7 @@ class MySQLUploader:
                     raise ValueError("分表方式必须是 'year' 或 'month' 或 'None'")
 
             # 准备数据
-            prepared_data, filtered_set_typ = self._prepare_data(data, set_typ, allow_null, db_name, table_name)
+            prepared_data, filtered_set_typ = self._prepare_data(data, set_typ, allow_null, db_name, table_name, auto_timestamps)
 
             # 检查数据库是否存在
             if not self._check_database_exists(db_name):
@@ -2080,6 +2180,70 @@ class MySQLUploader:
         except Exception as e:
             logger.error('创建索引失败', {'库': db_name, '表': table_name, '列': column, '错误': str(e)})
             raise
+
+    @_execute_with_retry
+    def _add_column_to_table(self, db_name: str, table_name: str, column: str, column_type: str, allow_null: bool = False):
+        """
+        添加列到指定表。
+
+        :param db_name: 数据库名
+        :param table_name: 表名
+        :param column: 需要添加的列名
+        :param column_type: 列的数据类型
+        :param allow_null: 是否允许空值，默认为False
+        """
+        db_name = self._validate_identifier(db_name, is_database=True)
+        table_name = self._validate_identifier(table_name)
+        column = self._validate_identifier(column)
+        
+        # 构建ALTER TABLE语句
+        null_constraint = "NULL" if allow_null else "NOT NULL"
+        
+        # 为新添加的列设置默认值
+        default_value = ""
+        if not allow_null:
+            column_type_lower = column_type.lower()
+            if any(t in column_type_lower for t in ['int', 'bigint', 'tinyint', 'smallint', 'mediumint']):
+                default_value = " DEFAULT 0"
+            elif any(t in column_type_lower for t in ['decimal', 'float', 'double']):
+                default_value = " DEFAULT 0.0"
+            elif any(t in column_type_lower for t in ['varchar', 'text', 'char', 'mediumtext', 'longtext']):
+                default_value = " DEFAULT 'none'"
+            elif 'date' in column_type_lower:
+                if 'datetime' in column_type_lower or 'timestamp' in column_type_lower:
+                    default_value = " DEFAULT '1970-01-01 00:00:00'"
+                else:
+                    default_value = " DEFAULT '1970-01-01'"
+            elif 'json' in column_type_lower:
+                default_value = " DEFAULT '{}'"
+        
+        sql = f'ALTER TABLE `{db_name}`.`{table_name}` ADD COLUMN `{column}` {column_type} {null_constraint}{default_value}'
+        
+        conn = None
+        try:
+            with self._get_connection() as conn:
+                with conn.cursor() as cursor:
+                    cursor.execute(sql)
+                conn.commit()
+                logger.debug('已为表添加列', {
+                    '库': db_name, 
+                    '表': table_name, 
+                    '列': column, 
+                    '类型': column_type,
+                    '允许空值': allow_null
+                })
+        except Exception as e:
+            logger.error('添加列失败', {
+                '库': db_name, 
+                '表': table_name, 
+                '列': column, 
+                '类型': column_type,
+                '错误': str(e),
+                'SQL': sql
+            })
+            if conn is not None:
+                conn.rollback()
+            raise
     
     def __enter__(self):
         return self
@@ -2431,6 +2595,93 @@ class MySQLUploader:
         
         return result_df
 
+    def _process_auto_timestamps(
+            self, 
+            data: Union[Dict, List[Dict], pd.DataFrame], 
+            set_typ: Dict[str, str], 
+            db_name: str, 
+            table_name: str
+    ) -> Tuple[Union[Dict, List[Dict], pd.DataFrame], Dict[str, str]]:
+        """
+        处理自动时间戳功能
+        
+        :param data: 原始数据
+        :param set_typ: 列类型定义
+        :param db_name: 数据库名
+        :param table_name: 表名
+        :return: 处理后的数据和更新后的set_typ
+        """
+        
+        # 定义时间戳列名
+        created_col = '创建时间'
+        updated_col = '更新时间'
+        current_time = datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        
+        # 复制set_typ以避免修改原始对象
+        updated_set_typ = set_typ.copy()
+        
+        # 添加时间戳列到set_typ
+        updated_set_typ[created_col] = 'DATETIME'
+        updated_set_typ[updated_col] = 'DATETIME'
+        
+        # 处理DataFrame格式的数据
+        if hasattr(data, 'shape') and hasattr(data, 'columns'):
+            import pandas as pd
+            df = data.copy()
+            
+            # 移除原始数据中可能存在的时间戳列
+            columns_to_remove = []
+            for col in df.columns:
+                if col in [created_col, updated_col]:
+                    columns_to_remove.append(col)
+                    logger.warning('移除原始数据中的时间戳列', {
+                        '库': db_name,
+                        '表': table_name,
+                        '列': col,
+                        '原因': '与自动时间戳功能冲突'
+                    })
+            
+            if columns_to_remove:
+                df = df.drop(columns=columns_to_remove)
+            
+            # 添加时间戳列
+            df[created_col] = current_time
+            df[updated_col] = current_time
+            
+            return df, updated_set_typ
+        
+        # 处理字典或字典列表格式的数据
+        else:
+            # 确保data是列表格式
+            if isinstance(data, dict):
+                data_list = [data]
+                is_single_dict = True
+            else:
+                data_list = data
+                is_single_dict = False
+            
+            # 处理每一行数据
+            processed_data = []
+            for row in data_list:
+                new_row = {}
+                
+                # 复制原始数据，但跳过可能存在的时间戳列
+                for key, value in row.items():
+                    if key not in [created_col, updated_col]:
+                        new_row[key] = value
+                
+                # 添加时间戳
+                new_row[created_col] = current_time
+                new_row[updated_col] = current_time
+                
+                processed_data.append(new_row)
+            
+            # 如果原始数据是单个字典，返回单个字典
+            if is_single_dict:
+                return processed_data[0], updated_set_typ
+            else:
+                return processed_data, updated_set_typ
+
 
 def main():
     dir_path = os.path.expanduser("~")

{mdbq-4.1.10 → mdbq-4.1.12}/mdbq.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: mdbq
-Version: 4.1.10
+Version: 4.1.12
 Home-page: https://pypi.org/project/mdbq
 Author: xigua, 
 Author-email: 2587125111@qq.com

mdbq-4.1.10/mdbq/__version__.py

@@ -1 +0,0 @@
-VERSION = '4.1.10'