きっかけ
Slack で CSV が送られてくる。スキーマ不明、エンコーディング不明、区切り文字不明。まず知りたいのは:
- 何行何列？
- 各カラムの型は？
- null はどこにどれだけ？
- 数値なら min/max/mean、文字列なら長さの範囲、日付なら期間
- 値の例をいくつか
pandas の df.describe() はこれに近いが、数値と非数値で別テーブルになるし、コールドスタートで1秒かかる。csvkit の csvstat は近いが事実上メンテされていない。
csv-profile を作った。純 Python、標準ライブラリのみ、57MB の Alpine コンテナ。
GitHub: https://github.com/sen-ltd/csv-profile
作ったもの
rows=4 cols=5 delimiter=comma encoding=utf-8-sig nulls=2 bytes≈120
id int nulls=0/4 (0%) distinct=4
min=1, max=4, mean=2.5, median=2.5, stdev=1.118
name string nulls=0/4 (0%) distinct=4
len=3..5
age int nulls=1/4 (25%) distinct=3
min=25, max=45, mean=33.33, median=30, stdev=8.498
active bool nulls=0/4 (0%) distinct=2
most_common='true' (×3)
signup date nulls=1/4 (25%) distinct=3
min=2024-01-15, max=2024-03-10
出力形式は text / markdown / json の3種類。
技術的なポイント
妥協しない型推論
型推論の設計には2つのアプローチがある:
確率的: 「95% が整数だから int」。pandas のデフォルト。例外は NaN にサイレント変換。
全か無か: 「全ての非 null 値が int にパースできたら int。1つでもダメなら string」。
csv-profile は後者を選んだ。プロファイラを使う理由はおかしな行を見つけるためであり、「ほぼ int」はまさにそのおかしな行を隠す。
TYPE_LADDER = ("int", "float", "bool", "date", "datetime", "string")
def infer_column_type(values, *, empty_as_null=True):
alive = {"int", "float", "bool", "date", "datetime"}
for raw in values:
if is_null(raw, empty_as_null=empty_as_null):
continue
if "int" in alive and not _try(parse_int, raw):
alive.discard("int")
if "float" in alive and not _try(parse_float, raw):
alive.discard("float")
if "bool" in alive and not _try(parse_bool, raw):
alive.discard("bool")
if "date" in alive and not _try(parse_date, raw):
alive.discard("date")
if "datetime" in alive and not _try(parse_datetime, raw):
alive.discard("datetime")
if not alive:
return "string"
for t in TYPE_LADDER:
if t in alive:
return t
return "string"
候補の集合を持ち、パース失敗するたびに候補を消す。全部消えたら即 string で打ち切り。最後に残った中で最も厳しい型（ラダー順）を返す。
ポイント:
- int は float としてもパースできるので、全 int カラムでは両方生存。ラダーで int が先なので int が勝つ
- 0/1 は int でも bool でもパースできる。ラダーで int が先（0/1 カラムは数値フラグであることが多い）
- 全 null カラムは string（シグナルがないので最も安全なデフォルト）
厳格なパーサ
def parse_int(value: str) -> int:
stripped = value.strip()
if "." in stripped or "e" in stripped.lower() or "_" in stripped:
raise ValueError("not an int")
return int(stripped)
Python の int() は寛容すぎるので、1.0 を int と判定しないよう自前でガード。parse_float は nan / inf を拒否。parse_date は YYYY-MM-DD のゼロパディングのみ受け付ける。
エンコーディング検出
chardet を入れたくないので、フォールバックチェーンで対応:
_FALLBACK_ENCODINGS = ("utf-8-sig", "utf-8", "latin-1")
utf-8-sig を最初にするのがコツ。Excel が出力する BOM を消費してくれる。plain UTF-8 を先にすると、BOM がヘッダーの先頭文字にくっつくバグが出る。「フォールバック順は成功の厳しさでソートする」という教訓。
latin-1 は全バイトが有効なので必ず成功する。Shift-JIS や GBK の判定が必要なら --encoding フラグで明示指定。
Markdown フォーマッタ
PR のコメントに貼る用:
out.append("| Column | Type | Nulls | Distinct | Min | Max | Example |")
パイプ文字を含むデータ値のエスケープ（.replace("|", "\\|")）を忘れるとテーブルが崩れる。テストで発見。
試してみる
docker build -t csv-profile https://github.com/sen-ltd/csv-profile.git
mkdir -p /tmp/demo
cat > /tmp/demo/users.csv << 'CSV'
id,name,age,active,signup
1,alice,30,true,2024-01-15
2,bob,25,false,2024-02-01
3,carol,,true,2024-03-10
4,dave,45,true,
CSV
docker run --rm -v /tmp/demo:/work csv-profile users.csv
docker run --rm -v /tmp/demo:/work csv-profile users.csv --format markdown
docker run --rm -v /tmp/demo:/work csv-profile users.csv --format json
57MB のイメージ、外部依存ゼロ、61テスト。
おわりに
CSV プロファイラに持たせるべき意見は「ファイルの中身について嘘をつかない」ことだ。「ほぼ数値」は嘘。全か無かの推論がその具体的な形。
小さくて意見のはっきりした CLI は、大きくて寛容なライブラリより使い道がある。ただし、その意見が正しい場合に限る。
SEN 合同会社の 100+ ポートフォリオシリーズ Entry #130。