csv-header-cleaner 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- csv_header_cleaner/__init__.py +3 -0
- csv_header_cleaner/__main__.py +4 -0
- csv_header_cleaner/cleaner.py +27 -0
- csv_header_cleaner/cli.py +79 -0
- csv_header_cleaner-0.1.0.dist-info/METADATA +144 -0
- csv_header_cleaner-0.1.0.dist-info/RECORD +10 -0
- csv_header_cleaner-0.1.0.dist-info/WHEEL +5 -0
- csv_header_cleaner-0.1.0.dist-info/entry_points.txt +2 -0
- csv_header_cleaner-0.1.0.dist-info/licenses/LICENSE +21 -0
- csv_header_cleaner-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import re
|
|
2
|
+
|
|
3
|
+
def clean_header(name: str) -> str:
|
|
4
|
+
|
|
5
|
+
# clean a name
|
|
6
|
+
name = name.lower().strip()
|
|
7
|
+
name = re.sub(r"[^a-z0-9]+", "_", name)
|
|
8
|
+
name = name.strip("_")
|
|
9
|
+
|
|
10
|
+
return name
|
|
11
|
+
|
|
12
|
+
def clean_headers(headers: list[str]) -> list[str]:
|
|
13
|
+
|
|
14
|
+
# clean whole list
|
|
15
|
+
new_headers: list[str] = []
|
|
16
|
+
seen: dict[str, int] = {}
|
|
17
|
+
|
|
18
|
+
for header in headers:
|
|
19
|
+
cleaned = clean_header(header)
|
|
20
|
+
if cleaned not in seen:
|
|
21
|
+
seen[cleaned] = 1
|
|
22
|
+
new_headers.append(cleaned)
|
|
23
|
+
else:
|
|
24
|
+
seen[cleaned] += 1
|
|
25
|
+
new_headers.append(f"{cleaned}_{seen[cleaned]}")
|
|
26
|
+
|
|
27
|
+
return new_headers
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import argparse
|
|
2
|
+
import csv
|
|
3
|
+
import json
|
|
4
|
+
import sys
|
|
5
|
+
from collections import Counter
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
|
|
8
|
+
from .cleaner import clean_header, clean_headers
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def process_file(input_path: Path, output_path: Path, report_path: Path | None) -> dict[str, list[str]]:
|
|
12
|
+
|
|
13
|
+
if not input_path.exists():
|
|
14
|
+
raise FileNotFoundError(f"input file not found: {input_path}")
|
|
15
|
+
if not input_path.is_file():
|
|
16
|
+
raise ValueError(f"input path is not a file: {input_path}")
|
|
17
|
+
|
|
18
|
+
with input_path.open("r", encoding="utf-8", newline="") as f:
|
|
19
|
+
reader = csv.reader(f)
|
|
20
|
+
rows = list(reader)
|
|
21
|
+
|
|
22
|
+
if len(rows) == 0:
|
|
23
|
+
raise ValueError("input file is empty")
|
|
24
|
+
|
|
25
|
+
original = rows[0]
|
|
26
|
+
body = rows[1:]
|
|
27
|
+
cleaned = clean_headers(original)
|
|
28
|
+
|
|
29
|
+
# Detect which cleaned base names appeared more than once.
|
|
30
|
+
bases = [clean_header(h) for h in original]
|
|
31
|
+
counts = Counter(bases)
|
|
32
|
+
duplicates = [name for name, count in counts.items() if count > 1]
|
|
33
|
+
|
|
34
|
+
report = {
|
|
35
|
+
"original_headers": original,
|
|
36
|
+
"cleaned_headers": cleaned,
|
|
37
|
+
"duplicates": duplicates,
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
# Write the cleaned CSV: new header row + original data rows.
|
|
41
|
+
with output_path.open("w", encoding="utf-8", newline="") as f:
|
|
42
|
+
writer = csv.writer(f)
|
|
43
|
+
writer.writerow(cleaned)
|
|
44
|
+
writer.writerows(body)
|
|
45
|
+
|
|
46
|
+
# Write JSON report only if the user asked for one.
|
|
47
|
+
if report_path is not None:
|
|
48
|
+
with report_path.open("w", encoding="utf-8") as f:
|
|
49
|
+
json.dump(report, f, indent=2)
|
|
50
|
+
|
|
51
|
+
return report
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def main(argv: list[str] | None = None) -> int:
|
|
55
|
+
parser = argparse.ArgumentParser(description="Clean messy CSV column headers.")
|
|
56
|
+
parser.add_argument("input", help="Path to input CSV file")
|
|
57
|
+
parser.add_argument("--output", required=True, help="Path to write cleaned CSV")
|
|
58
|
+
parser.add_argument("--report", default=None, help="Optional path to write JSON report")
|
|
59
|
+
args = parser.parse_args(argv)
|
|
60
|
+
|
|
61
|
+
input_path = Path(args.input)
|
|
62
|
+
output_path = Path(args.output)
|
|
63
|
+
report_path = Path(args.report) if args.report else None
|
|
64
|
+
|
|
65
|
+
try:
|
|
66
|
+
report = process_file(input_path, output_path, report_path)
|
|
67
|
+
except FileNotFoundError as e:
|
|
68
|
+
print(f"Error: {e}", file=sys.stderr)
|
|
69
|
+
return 1
|
|
70
|
+
except ValueError as e:
|
|
71
|
+
print(f"Error: {e}", file=sys.stderr)
|
|
72
|
+
return 1
|
|
73
|
+
|
|
74
|
+
print(f"Cleaned {len(report['cleaned_headers'])} headers -> {output_path}")
|
|
75
|
+
return 0
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
if __name__ == "__main__":
|
|
79
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: csv-header-cleaner
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Clean messy CSV column headers into consistent snake_case names.
|
|
5
|
+
Author-email: Sabir Hussain Balal <sabirhusseinbalal@outlook.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/sabirhusseinbalal/csv-header-cleaner
|
|
8
|
+
Project-URL: Repository, https://github.com/sabirhusseinbalal/csv-header-cleaner
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: Operating System :: OS Independent
|
|
11
|
+
Requires-Python: >=3.10
|
|
12
|
+
Description-Content-Type: text/markdown
|
|
13
|
+
License-File: LICENSE
|
|
14
|
+
Dynamic: license-file
|
|
15
|
+
|
|
16
|
+
# csv-header-cleaner
|
|
17
|
+
|
|
18
|
+
A neat little Python tool that cleans messy CSV column headers into consistent `snake_case` names.
|
|
19
|
+
|
|
20
|
+
## The Problem
|
|
21
|
+
If you download a CSV data set, you'll frequently see that the column names are not very tidy, for example:
|
|
22
|
+
|
|
23
|
+
- `First Name`
|
|
24
|
+
- `Last Name`
|
|
25
|
+
- `Customer Name (Full)`
|
|
26
|
+
- `FIRST NAME`
|
|
27
|
+
|
|
28
|
+
Working with CSV files can be more difficult due to spaces, punctuation and inconsistent naming.
|
|
29
|
+
Other issues may arise when working with data when there is a duplicate column name.
|
|
30
|
+
|
|
31
|
+
## The Solution
|
|
32
|
+
This package will convert your csv headers, remove all spaces, delete punctuation, lower case everything and preserve numbers. It also supports duplicates; for example by adding a sequence number (e.g. `first_name_2`).
|
|
33
|
+
|
|
34
|
+
```python
|
|
35
|
+
from csv_header_cleaner import clean_headers
|
|
36
|
+
|
|
37
|
+
headers = ["First Name", "first name", "FIRST NAME", "Age"]
|
|
38
|
+
print(clean_headers(headers))
|
|
39
|
+
# Output: ['first_name', 'first_name_2', 'first_name_3', 'age']
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Features
|
|
45
|
+
- Clean a single column name.
|
|
46
|
+
- Clean a list of column names.
|
|
47
|
+
- Handle duplicate headers.
|
|
48
|
+
- Read and write CSV files via the command line.
|
|
49
|
+
- Save cleaned CSV files.
|
|
50
|
+
- Create an optional json report.
|
|
51
|
+
- No external run-time requirements.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Installation
|
|
56
|
+
```bash
|
|
57
|
+
pip install csv-header-cleaner
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Python Usage
|
|
63
|
+
There are two functions available to import from this package.
|
|
64
|
+
|
|
65
|
+
## Clean one header
|
|
66
|
+
```python
|
|
67
|
+
from csv_header_cleaner import clean_header
|
|
68
|
+
|
|
69
|
+
print(clean_header("First Name"))
|
|
70
|
+
```
|
|
71
|
+
- Output:
|
|
72
|
+
```python
|
|
73
|
+
first_name
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Clean multiple headers
|
|
77
|
+
```python
|
|
78
|
+
from csv_header_cleaner import clean_headers
|
|
79
|
+
|
|
80
|
+
headers = ["First Name", "first name", "FIRST NAME", "Age"]
|
|
81
|
+
|
|
82
|
+
print(clean_headers(headers))
|
|
83
|
+
```
|
|
84
|
+
- Output:
|
|
85
|
+
```python
|
|
86
|
+
['first_name', 'first_name_2', 'first_name_3', 'age']
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## How to use (Command Line)
|
|
90
|
+
It can also be used in your terminal. It provides the ability to save a JSON report and prints all options with `-h` or `--help`.
|
|
91
|
+
```bash
|
|
92
|
+
csv-header-cleaner input.csv --output cleaned.csv --report report.json
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Requirements
|
|
98
|
+
- Python 3.10 or newer.
|
|
99
|
+
- No external runtime dependencies.
|
|
100
|
+
|
|
101
|
+
## Current Limitations
|
|
102
|
+
- The tool cleans only the headers of the columns.
|
|
103
|
+
- It does not alter the values of the data in the CSV.
|
|
104
|
+
- It currently reads and writes files in UTF-8 encoding.
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## Running Tests
|
|
109
|
+
### Clone the repository:
|
|
110
|
+
```bash
|
|
111
|
+
git clone https://github.com/sabirhusseinbalal/csv-header-cleaner.git
|
|
112
|
+
cd csv-header-cleaner
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Install the development tools and run the tests:
|
|
116
|
+
```bash
|
|
117
|
+
python -m pip install pytest
|
|
118
|
+
python -m pytest
|
|
119
|
+
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## How to report a problem
|
|
125
|
+
If you find a bug or have a feature request, please [open an issue](https://github.com/sabirhusseinbalal/csv-header-cleaner/issues/) on GitHub. I will try my best to respond quickly.
|
|
126
|
+
|
|
127
|
+
## License
|
|
128
|
+
|
|
129
|
+
MIT. See [LICENSE](LICENSE).
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
# Note
|
|
134
|
+
- This is the first version, which means there are some known edge cases.
|
|
135
|
+
- example:
|
|
136
|
+
```python
|
|
137
|
+
headers = ["name", "name", "name_2"]
|
|
138
|
+
```
|
|
139
|
+
- result might be:
|
|
140
|
+
```python
|
|
141
|
+
["name", "name_2", "name_2"]
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
- This is a problem because two columns now have the same name. This will be fixed in a later version (0.1.1).
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
csv_header_cleaner/__init__.py,sha256=JT0R1zCJsK6c0E-7bYQ9TBdPZrvXagJ86Sl6nSkdFeM,93
|
|
2
|
+
csv_header_cleaner/__main__.py,sha256=dlUlpbDREBvZ3EZbGtRNlpLJryM0RTGD3zUPraT5m3M,78
|
|
3
|
+
csv_header_cleaner/cleaner.py,sha256=KLTfHbvb-vHQ_wnkz_2d_yJmyKg2r7TVKvxAHtHsAvA,625
|
|
4
|
+
csv_header_cleaner/cli.py,sha256=DBhGGs-__llkYkXhPXVr_kkx3x3i0qC7T1M5mUK_blE,2490
|
|
5
|
+
csv_header_cleaner-0.1.0.dist-info/licenses/LICENSE,sha256=xELvBUuKbruxwMjxufjaR9VIqNGFzCIl7x7tn2NVmx8,1075
|
|
6
|
+
csv_header_cleaner-0.1.0.dist-info/METADATA,sha256=r9yw-hjqlyRMlo0N-raiHzAl05p2eUam-oZTbkz8eqc,3709
|
|
7
|
+
csv_header_cleaner-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
8
|
+
csv_header_cleaner-0.1.0.dist-info/entry_points.txt,sha256=xCdyK3PGgv7jdCgANqGslt_j5HgtTKmSfRHjOIGzRqg,67
|
|
9
|
+
csv_header_cleaner-0.1.0.dist-info/top_level.txt,sha256=g5MGWU_zmaE2HNmRIuVGbcG566ESROHHwDT6CRPQsTw,19
|
|
10
|
+
csv_header_cleaner-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Sabir Hussain Balal
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
csv_header_cleaner
|