csv-handler

核心用法

CSV Handler 是一款专为建筑行业设计的 CSV 数据处理技能，主要解决工程软件（如 Primavera P6、AutoCAD、各类造价软件）导出 CSV 文件时常见的编码混乱、分隔符不一致、列名不规范等问题。核心功能包括：

1. 智能文件分析：通过 profile_csv()() 方法自动检测文件编码（使用 chardet 库）、分隔符类型、行列结构，生成完整的 CSV 文件档案
2. 自动读取与清洗：read_csv()() 方法支持全自动检测或手动指定参数，内置数据清理流程（标准化列名、去除空行空列、字符串去空格）
3. 批量合并与拆分：merge_csvs()() 支持多文件按列合并或纵向拼接；split_csv()() 可按指定列值将数据拆分为多个独立文件
4. 专业场景适配：提供 ScheduleCSVHandler（进度计划处理，自动识别日期列）和 CostCSVHandler（成本数据处理，自动识别金额列并去除货币符号）两个专用子类

显著优点

• 零配置上手：无需预先了解文件编码或分隔符类型，自动检测准确率覆盖 UTF-8、Latin-1、CP1252 等建筑软件常用编码
• 健壮的错误处理：on_bad_lines='skip'' 机制确保损坏行不会导致读取失败，适合处理大型工程导出文件
• 建筑场景深度优化：针对进度计划（WBS、任务日期）和造价数据（工程量、单价、合价）的列名识别与类型转换做了专门设计
• 纯本地处理：无网络依赖，敏感工程数据不会离开本地环境

潜在缺点与局限性

• 内存限制：依赖 pandas 的 low_memory=False 模式处理大文件，超大型 CSV（GB 级）可能导致内存不足
• 编码检测非 100% 准确：chardet 对短文件或特殊编码的检测存在误判可能，极端情况下需手动指定
• 日期格式识别有限：自动日期转换依赖 pandas 的 to_datetime，对非标准日期格式（如 "2024年3月15日"）识别能力有限
• 无可视化界面：纯代码 API，需要一定的 Python 基础

适合的目标群体

• 建筑/工程公司的数据分析师、BIM 工程师
• 需要处理造价软件、进度管理软件导出数据的成本工程师、计划工程师
• 从事建筑数据治理、数据仓库建设的开发团队
• 学术研究中的建筑信息化（AEC IT）研究人员

使用风险

• 性能风险：处理百万行级 CSV 时内存占用较高，建议在服务器环境使用
• 依赖版本：依赖 pandas 和 chardet，需确保环境兼容性
• 数据覆盖风险：export_csv 和 split_csv 会直接写入指定路径，需注意避免覆盖重要文件

核心用法

CSV Handler 是专为建筑行业设计的 CSV 处理工具，解决从施工管理软件导出数据时的编码混乱、分隔符不一致、格式脏污等常见问题。核心功能包括：

• 智能探测：自动检测文件编码（chardet）、分隔符（,;\t|）、表头存在性
• 数据清洗：标准化列名（小写下划线）、剔除空行列、修剪空白字符
• 类型转换：自动识别日期/数值列，支持自定义类型映射
• 批量操作：多文件合并（按列关联或纵向拼接）、按列值拆分为独立文件
• 专项处理器：ScheduleCSVHandler（进度表日期解析）、CostCSVHandler（成本金额清洗）

使用示例

handler = ConstructionCSVHandler()
profile = handler.profile_csv("export.csv")  # 先分析文件特征
df = handler.read_csv("export.csv", clean=True)  # 一键读取并清洗

显著优点

1. 建筑场景深度适配：针对 P6/MS Project 等软件导出的特殊格式优化，内置日期列、成本列的智能识别
2. 零配置开箱即用：无需手动指定编码或分隔符，自动处理 UTF-8/BOM/Latin-1 等常见编码问题
3. 防御性编程：on_bad_lines='skip'、errors='coerce' 等容错机制，避免脏数据导致崩溃
4. 可扩展架构：基类设计清晰，易于派生专用处理器（如材料清单、设备台账等）

潜在缺点与局限性

1. 性能瓶颈：chardet 采样仅前 10KB，超大文件（>100MB）检测可能不准；全量读取依赖 pandas，内存占用较高
2. 探测启发式局限：分隔符检测基于频次统计，若数据内容本身含大量逗号/分号可能误判；编码检测非 100% 准确
3. 功能边界未声明：未明确最大支持文件大小、编码格式白名单、损坏 CSV 的处理策略
4. 依赖版本风险：示例代码依赖 pandas 和 chardet，但未指定版本兼容性要求

适合人群

• 建筑数据分析师：处理多软件导出的进度、成本、物料 CSV
• BIM 工程师：清洗模型属性导出表格，统一字段格式
• 施工管理 IT：开发数据 ETL 流程，对接 ERP/造价软件

常规风险

• 数据丢失风险：on_bad_lines='skip' 会静默丢弃异常行，关键数据可能遗漏
• 类型推断误判：自动日期/数值转换可能误识别（如项目编号 "2023-001" 被转为日期）
• 编码回退风险：检测失败时回退到 utf-8，可能产生乱码而非报错，导致下游分析错误
• 无事务回滚：文件操作直接覆盖/写入，建议处理前手动备份原文件