# python-csv-deduplicator

**Repository Path**: Zjy_0729/python-csv-deduplicator

## Basic Information

- **Project Name**: python-csv-deduplicator
- **Description**: Python CSV 数据去重与批量处理工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-27
- **Last Updated**: 2026-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CSV 数据清洗与去重工具

## 1. 项目简介

这是一个基于 Python 标准库开发的 CSV 数据清洗工具，支持单文件去重、按指定字段去重和批量处理目录中的 CSV 文件。

工具采用确定性的规则处理数据，不依赖大模型或第三方库，适用于客户数据整理、重复记录清理及日常 CSV 文件处理等基础场景。

## 2. 核心功能

- **整行去重**：所有字段内容完全一致时，才认定为重复记录。
- **指定列去重**：支持按手机号等指定字段去重。
- **保留首次记录**：发现重复数据时，保留第一次出现的记录。
- **批量处理**：遍历输入目录中的 CSV 文件，逐个处理并汇总结果。
- **结果统计**：显示输入记录数、输出记录数和删除的重复记录数。
- **输入校验**：检查文件是否存在、表头是否合法、数据行字段数量是否正确。
- **文件保护**：默认不覆盖已有输出文件，并防止输入文件被输出文件覆盖。
- **异常隔离**：批量处理时，单个文件失败不会阻止其他文件继续处理。
- **自动化测试**：使用 Python 标准库 `unittest` 验证核心功能和异常场景。

## 3. 项目结构

```text
python-csv-demo/
├── csv_deduplicator.py    # 主程序
├── deduplicate.py         # 初始版本
├── test_deduplicator.py   # 自动化测试
├── customers.csv          # 示例输入数据
├── test-data/             # 测试数据
├── output/                # 输出文件目录
└── README.md              # 项目说明
```

## 4. 环境要求

- Python 3
- 无需安装第三方依赖
- Windows、macOS 或 Linux 终端均可运行

## 5. 使用方法

在项目根目录打开终端。

### 5.1 单文件整行去重

```powershell
python csv_deduplicator.py customers.csv -o .\output\customers_clean.csv
```

不指定 `-o` 时，程序默认在输入文件名后添加 `_clean`。

### 5.2 按指定字段去重

例如，按手机号去重：

```powershell
python csv_deduplicator.py customers.csv -o .\output\customers_by_phone.csv --key phone
```

`--key phone` 表示只比较 `phone` 字段。手机号相同的记录只保留第一条，即使其他字段不同，也会被视为重复记录。

指定的字段不存在时，程序会提示错误及当前 CSV 可用字段。

### 5.3 批量处理目录

```powershell
python csv_deduplicator.py .\test-data --batch -o .\output\batch
```

程序会扫描输入目录下的 CSV 文件，将处理结果保存到输出目录，并报告每个文件的处理情况。

批量处理也支持指定去重字段：

```powershell
python csv_deduplicator.py .\test-data --batch -o .\output\batch --key phone
```

使用前请确认输入文件均包含指定字段。批量处理时，失败文件会被单独报告，其他文件仍会继续处理。

输出目录不能与输入目录相同，也不能位于输入目录内部。

### 5.4 允许覆盖已有输出文件

确认可以覆盖目标文件后，添加 `--overwrite`：

```powershell
python csv_deduplicator.py customers.csv -o .\output\customers_clean.csv --overwrite
```

批量模式同样支持该参数：

```powershell
python csv_deduplicator.py .\test-data --batch -o .\output\batch --overwrite
```

### 5.5 查看命令帮助

```powershell
python csv_deduplicator.py --help
```

## 6. 处理示例

输入数据：

```csv
name,city,phone
张三,北京,13800000001
李四,上海,13800000002
张三,北京,13800000001
王五,广州,13800000003
李四,深圳,13800000002
```

使用默认整行去重后：

```csv
name,city,phone
张三,北京,13800000001
李四,上海,13800000002
王五,广州,13800000003
李四,深圳,13800000002
```

处理统计：

- 输入记录数：5
- 输出记录数：4
- 删除重复记录数：1

两条李四记录虽然姓名和手机号相同，但城市不同，因此默认模式会保留两条记录。

如果改为 `--key phone`，相同手机号只保留首次出现的记录，示例数据将从 5 条记录减少为 3 条。

## 7. 自动化测试

项目使用 Python 标准库 `unittest` 编写自动化测试，无需安装额外测试框架。

运行测试：

```powershell
python -m unittest -v test_deduplicator.py
```

当前测试结果：

- 测试用例：13 项
- 通过：13 项
- 失败：0 项

测试覆盖以下场景：

1. 删除完全重复的记录。
2. 保留字段存在差异的记录。
3. 按指定列去重，并保留首次出现的记录。
4. 处理只有表头的 CSV 文件。
5. 检测输入文件不存在。
6. 检测空文件。
7. 禁止输入文件和输出文件相同。
8. 禁止意外覆盖已有输出文件。
9. 检测数据行字段数量异常。
10. 检测指定的去重列不存在。
11. 批量处理多个 CSV 文件。
12. 单个文件处理失败后继续处理其他文件。
13. 禁止将批量输出目录放在输入目录内部。

## 8. 实现思路

整体处理流程如下：

1. 接收输入路径、输出路径及处理选项。
2. 校验输入文件或目录，以及输出路径。
3. 读取 CSV 表头和数据行。
4. 根据处理模式选择整行去重或按指定列去重。
5. 保留首次出现的记录。
6. 将处理结果写入输出文件。
7. 返回输入记录数、输出记录数和删除的重复记录数。
8. 批量模式下逐个处理 CSV 文件，统计成功与失败数量，并在单个文件失败后继续处理其他文件。

该工具主要实践了 Python 文件处理、集合去重、命令行参数设计、异常处理、批量任务处理和自动化测试。

## 9. 当前限制

- 仅支持 CSV 格式，不直接处理 Excel 工作簿。
- 默认按照整行内容去重；指定 `--key` 后，按照单个指定列去重。
- 暂不支持多个字段组合去重。
- 不会自动识别姓名、电话等字段中的业务等价关系，也不会自动清洗空格或统一手机号格式。
- 批量模式仅扫描输入目录的第一层，不递归处理子目录。
- 当前数据处理方式尚未针对超大文件进行专门的流式处理和性能优化。
- 13 项自动化测试全部通过，但这不代表所有异常、边界情况和生产环境场景均已覆盖。

## 10. 项目总结

本项目从基础 CSV 去重脚本逐步完善为具备命令行参数、整行及指定列去重、批量处理、异常隔离、文件保护和自动化测试的轻量级数据处理工具。

项目验证了从功能实现、异常处理、测试验证到文档整理的基本工程化流程，可作为 CSV 数据清洗和批量处理类小型需求的项目展示案例。