Csv Handler

核心用法

CSV Handler 是针对建筑工程软件导出数据的专业CSV处理工具，基于 Python pandas 生态构建。主要功能包括：

1. 智能文件识别

• detect_encoding(): 使用 chardet 库自动检测文件编码（支持 UTF-8、Latin-1、CP1252 等）
• detect_delimiter(): 基于样本频率分析自动识别分隔符（逗号、分号、制表符、管道符）
• profile_csv(): 生成完整的文件画像（编码、分隔符、表头判断、行列数）

2. 数据清洗 pipeline

• clean_dataframe(): 列名规范化（小写+下划线替换空格）、空行列剔除、字符串去空格
• convert_types(): 智能类型转换，自动识别数值列和日期列

3. 批量操作

• merge_csvs(): 多文件合并，支持基于指定列的 join 或简单 concat
• split_csv(): 按列值分组导出独立文件

4. 专业化子类

• ScheduleCSVHandler: 专门针对进度计划（如 P6 导出），自动识别日期列
• CostCSVHandler: 针对成本估算，自动清理货币符号并转为数值

显著优点

• 零配置开箱即用：无需手动指定编码和分隔符，解决欧洲软件常见的分号分隔、中文系统 GBK 编码等痛点
• 健壮的错误处理：on_bad_lines='skip' 和 errors='replace' 确保脏数据不中断流程
• 建筑领域语义感知：内置对 "cost/price/amount"、"date/start/end" 等字段的识别规则

潜在缺点与局限性

• 依赖较重：需要 Python3 + pandas + chardet，非轻量环境
• 大文件性能：low_memory=False 和全量行计数可能占用大量内存
• 日期识别有限：仅基于列名关键词匹配，无法处理非标准日期格式
• 合并策略简单：仅支持 outer join，无复杂的冲突解决机制

适合人群

• 建筑工程师处理 ERP/PM 软件（如 SAP、P6、CostX）导出的数据
• 数据分析师整合多期成本报表或进度更新
• 需要批量规范化历史项目数据的档案管理人员

常规风险

• 编码检测误判：chardet 对短文件或小样本可能返回错误编码，建议关键任务前用 profile_csv() 验证
• 类型转换数据丢失：强制 to_numeric(errors='coerce') 会将无法解析的值为 NaN，可能丢失原始信息
• 路径注入：split_csv 的输出路径直接拼接用户输入，虽使用 pathlib 但仍需确保 output_dir 可信

核心用法

CSV Handler 专为建筑行业数据交换场景设计，解决从 Primavera P6、AutoCAD、Revit 等软件导出 CSV 时常见的编码混乱、分隔符不一致、列名不规范等问题。

主要功能模块：

• 智能检测：自动识别文件编码（chardet）、分隔符（逗号/分号/制表符/管道符）、表头存在性
• 数据清洗：标准化列名（小写+下划线）、去除空行空列、字符串去空白
• 类型转换：自动识别日期、数值列，支持自定义类型映射
• 批量处理：多文件合并（支持按指定列关联）、按列值拆分为多个文件
• 专用解析器：ScheduleCSVHandler 处理进度计划（自动识别日期列），CostCSVHandler 处理成本数据（自动清理货币符号）

典型工作流：
1. profile_csv() 探测文件特征 → 2. read_csv() 加载数据 → 3. clean_dataframe() 清洗 → 4. convert_types() 优化类型 → 5. 业务分析或导出

显著优点

1. 零配置启动：无需手动指定编码或分隔符，降低非技术人员使用门槛
2. 建筑场景深度优化：内置进度计划、成本数据专用解析器，识别 cost/price/amount/qty 等特征列名
3. 容错性强：on_bad_lines='skip'、errors='replace' 等参数确保脏数据不中断流程
4. 纯文档型设计：仅提供代码示例和 API 参考，无可执行文件，安全风险极低

潜在局限

• 非独立工具：需用户自行集成到 Python 环境，依赖 pandas 和 chardet 库
• 大文件性能：sum(1 for _ in f) 方式统计行数对 GB 级文件效率较低，未实现流式处理
• 编码检测局限：chardet 对短文本或小样本文件可能误判，建议关键文件手动验证
• 合并逻辑简单：多文件合并时仅支持单键关联，复杂 join 场景需自行扩展

适合人群

• 建筑/工程行业数据分析师、BIM 工程师
• 需批量处理 ERP、项目管理软件导出数据的财务人员
• 有一定 Python 基础、希望减少数据预处理时间的开发者

常规风险

• CSV 注入风险：处理来自不可信来源的文件时，公式注入（=CMD|' ...）可能影响下游 Excel 用户
• 自动类型推断误差：数值型 ID（如 "00123"）可能被转换为整数 123，建议关键字段显式指定类型
• 内存占用：默认 low_memory=False 加载完整文件，超大文件建议分块读取