Сделать отчёт по CSV
Собирает Markdown-отчёт с типами колонок, пропусками, уникальностью и частыми значениями.
Что делает скрипт
Скрипт читает CSV и по каждой колонке считает непустые и пустые ячейки, количество уникальных значений, числовой диапазон и топ частых значений. В отчёт также попадает таблица с первыми строками. Это быстрый способ понять новую выгрузку без открытия Excel.
- Отчёт читает файл целиком и держит строки в памяти. Для очень больших CSV используйте выборку.
Быстрый старт
python csv_report.py --input data.csv --output report.md
Скачайте файл, откройте терминал в папке со скриптом и выполните команду.
В Linux и macOS интерпретатор может называться python3, в Windows - python или py.
Другие варианты
python csv_report.py --input sales.csv --title 'Отчёт по продажам' --sample 10python csv_report.py --input users.csv --output docs/users.md --force
Что понадобится
winget install Python.Python.3.12
brew install python
sudo apt install python3
csv_report.py
#!/usr/bin/env python3
"""Markdown-отчёт по CSV."""
from __future__ import annotations
import argparse
import csv
from collections import Counter
from datetime import datetime
from pathlib import Path
def escape(value: str) -> str:
return value.replace("|", "\\|").replace("\n", " ").strip()
def is_number(value: str) -> bool:
try:
float(value.replace(",", "."))
except ValueError:
return False
return True
def main() -> int:
parser = argparse.ArgumentParser(description="Отчёт по CSV")
parser.add_argument("--input", type=Path, required=True, help="Исходный CSV")
parser.add_argument("--output", type=Path, default=Path("report.md"), help="Результат")
parser.add_argument("--title", default="", help="Заголовок отчёта")
parser.add_argument("--sample", type=int, default=5, help="Строк в примере")
parser.add_argument("--delimiter", default=",", help="Разделитель колонок")
parser.add_argument("--force", action="store_true", help="Перезаписать выходной файл")
args = parser.parse_args()
source = args.input.expanduser().resolve()
target = args.output.expanduser().resolve()
if not source.is_file():
parser.error(f"Файл не найден: {source}")
if source == target:
parser.error("Выходной файл не должен совпадать с исходным")
if target.exists() and not args.force:
parser.error(f"Файл уже существует: {target}. Добавьте --force")
if args.sample < 0:
parser.error("--sample не может быть отрицательным")
if len(args.delimiter) != 1:
parser.error("Разделитель должен состоять из одного символа")
with source.open("r", encoding="utf-8-sig", newline="") as handle:
reader = csv.DictReader(handle, delimiter=args.delimiter)
if reader.fieldnames is None:
parser.error("Не удалось прочитать заголовок")
columns = list(reader.fieldnames)
rows = list(reader)
lines = [f"# {args.title or 'Отчёт по CSV'}", ""]
lines.append(f"Источник: `{source}`")
lines.append("")
lines.append(f"Строк: {len(rows)}. Колонок: {len(columns)}.")
lines.append("")
lines.append(f"Сформировано: {datetime.now().strftime('%Y-%m-%d %H:%M')}")
lines.append("")
lines.append("## Колонки")
lines.append("")
lines.append("| Колонка | Тип | Непустых | Пустых | Уникальных | Минимум | Максимум | Среднее |")
lines.append("|---|---|---|---|---|---|---|---|")
counters: dict[str, Counter] = {}
for column in columns:
values = [(row.get(column) or "").strip() for row in rows]
filled = [value for value in values if value != ""]
empty = len(values) - len(filled)
unique = len(set(filled))
numeric = bool(filled) and all(is_number(value) for value in filled)
counters[column] = Counter(filled)
if numeric:
numbers = [float(value.replace(",", ".")) for value in filled]
minimum = f"{min(numbers):g}"
maximum = f"{max(numbers):g}"
average = f"{sum(numbers) / len(numbers):.2f}"
kind = "число"
else:
minimum = maximum = average = ""
kind = "текст" if filled else "пусто"
lines.append(f"| {escape(column)} | {kind} | {len(filled)} | {empty} | {unique} | {minimum} | {maximum} | {average} |")
lines.extend(["", "## Частые значения", ""])
for column in columns:
top = counters[column].most_common(5)
if not top:
continue
lines.append(f"### {escape(column)}")
lines.append("")
lines.append("| Значение | Количество |")
lines.append("|---|---|")
for value, count in top:
lines.append(f"| {escape(value)} | {count} |")
lines.append("")
if args.sample and rows:
lines.extend(["## Первые строки", ""])
lines.append("| " + " | ".join(escape(column) for column in columns) + " |")
lines.append("| " + " | ".join("---" for _ in columns) + " |")
for row in rows[: args.sample]:
lines.append("| " + " | ".join(escape(row.get(column) or "") for column in columns) + " |")
lines.append("")
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text("\n".join(lines), encoding="utf-8")
print(f"Строк: {len(rows)}")
print(f"Колонок: {len(columns)}")
print(f"Результат: {target}")
return 0
if __name__ == "__main__":
raise SystemExit(main())
Скрипты работают с файлами и настройками системы. Перед запуском прочитайте код и проверьте пути. Особенно если скрипт удаляет, перезаписывает или перемещает данные.