◆ 【ツール配布】CSVを取り込む前に全行まとめて検査する｜「1件直して再実行」を終わらせる(Python標準ライブラリのみ・全コード)

基幹システムに新しい注文データを流し込もうとして、1行目のエラーで止まった経験がある人は多いと思う。「必須項目が空です」とだけ表示され、取込画面を閉じてCSVを開き、該当行を直してもう一度アップロードする。すると今度は3行目で「日付の書式が違います」と言われる。また直して、また流し込む。5回目でようやく「取込が完了しました」と出たときには、30分近く経っていた。

問題は、エラーが1件ずつしか教えてもらえないことにある。取込先のシステムは、最初に見つけた不備でそこから先を読むのをやめてしまう。1件直すたびに、まだ見ぬ次の不備が現れるまでは、それが何件あるのかすら分からない。担当者に「あと何件ありそうですか」と聞かれても、「やってみないと分かりません」としか答えられない。

この記事で配布するのは、CSVを取込先に渡す前に、手元で機械的に検査するコマンドラインツールである。JSON形式の定義ファイルに「この列は必須」「この列は整数で1〜100の範囲」といった条件を書いておくと、CSVの全行を1回だけ走査して、駄目な箇所をまとめて報告する。直しはしない。どこが駄目かを、行番号・列名・値・理由の4点セットで出すだけである。だが、この「全部まとめて報告する」という一点だけで、「1件直して再実行」を繰り返す作業がなくなる。Python標準ライブラリのみで動く1ファイルのツールで、追加のインストールは要らない。

■ この無料部分だけでできること

- 「最初のエラーで止まる」検査が、なぜ実務では一番時間を食うのかが構造として分かる

- 報告を「行番号・列名・値・理由」の4点セットにした理由が分かる

- 終了コードを0/1/2に分け、データの不備と設定のミスを区別する設計の意図が分かる

- 定義ファイル自体を先に検査してから、初めてCSVを読みにいく理由が分かる

- 定義ファイルにコードを書かせない(evalを使わない)設計が、何を防いでいるかが分かる

- 直す機能をあえて作らなかった理由が分かる

- ツールが無くても、表計算ソフトの機能だけで同じ考え方を手で再現する方法が分かる

- このツールが検査していないこと・検査できないことが具体的に分かる

無料部分だけで、設計の考え方はすべて説明している。読んだうえで「これなら自分で書ける」と判断できた人は、購入せずにそのまま自分の手で作ってもらって構わない。

■ こんなところで止まっていませんか

- 基幹システムや会計ソフトにCSVを取り込むたびに、1件のエラーで止まり、直しては再アップロードを繰り返している

- 「あと何件エラーがありそうか」と聞かれても、最後までやり直してみないと分からない

- 取込先のエラーメッセージが「3行目でエラー」としか言わず、どの列のどの値が悪いのか自分で見に行っている

- 定期的に流し込むCSVで、担当者ごとに毎回同じような不備(空欄、桁あふれ、コード値の入力ミス)を見つけては直している

- 検査用のスクリプトをその場しのぎで書いていて、列が増えるたびに書き直している

- バッチ処理に組み込みたいが、失敗の原因が「データが悪いのか」「設定を間違えたのか」ログだけでは判別できない

■ なぜ「最初のエラーで止まる」検査がいちばん時間を食うのか

多くの検査処理は、上から順に見ていって、最初に条件を満たさない箇所が見つかった時点で止まる。実装としては自然な作り方で、1件目のエラーを見つけて報告するだけなら、これでも用は足りる。

だが実務では、CSVに不備があるとき、それはたいてい1件では済まない。同じ入力担当者が同じ手順で複数行を入力していれば、同じ種類の間違いが複数行に散らばっているのが普通である。最初のエラーで止まる検査は、この「複数行に散らばった不備」を1件ずつしか見せてくれない。直す→流し込む→次のエラーが出る→また直す、というサイクルを、不備の件数だけ繰り返すことになる。件数が2〜3件ならまだしも、10件を超えてくると、この往復だけで作業時間の大半を持っていかれる。

このツールは、CSVを1回だけ走査し、全行・全列を最後まで検査してから、見つかった不備を一度に報告する。列ごとの検査で1件エラーが見つかっても、その列の検査を続け、次の列・次の行の検査にも進む(コードでいえばcontinueで次の検査項目に移るだけで、breakでループ全体を止めることはしていない)。実行結果には「エラー件数」「エラーのある行数」「正常な行数」の内訳も出るので、直す前に「今回はどのくらいの規模の作業になりそうか」を把握できる。1回の実行で全体像が見える、というのが、このツール最大の実用価値だと考えている。

■ 報告を「行番号・列名・値・理由」の4点セットにした理由

検査結果が「7行目に問題があります」とだけ返ってくるツールは少なくない。だが、これだけでは受け取った側は結局CSVを開いて7行目を目で見て、どの列が悪いのか、どんな値が入っているのか、なぜ駄目なのかを自分で探す羽目になる。検査した人と直す人が別の担当者である場合、この「探す」作業のために検査結果とは別にCSVを共有する必要も出てくる。

このツールが1件のエラーごとに出すのは、行番号・列名・値・理由の4つである。「行8 列'quantity' 値='abc': 整数(integer)として解釈できません」のように、どこの何が、なぜ駄目なのかが1行で完結する。この4点があれば、検査した本人でなくても、この文面をそのまま担当者に転送するだけで直してもらえる。検査結果を読むために元のCSVを開き直す必要がない。

--csvオプションを付けると、この4点セットをrow,column,value,reasonの4列を持つ機械可読なCSVとしても書き出せる。画面に出す人間向けの報告と、表計算ソフトに読み込んでフィルタや並べ替えをかけるための機械可読な出力を、両方用意しているのは、検査結果を「読む人」と「絞り込んで一括処理したい人」の両方に対応するためである。既に出力先にファイルがある場合は既定では書き込まず、--forceを指定したときだけ上書きする。過去の検査結果を誤って消してしまう事故を避けるための、地味だが実務では効く仕様である。

■ 終了コードを0/1/2に分け、データの不備と設定のミスを区別する理由

このツールはコマンドラインの終了コードを0・1・2の3種類に分けている。0はエラーなし、1はデータにエラーがある、2は定義ファイルまたは引数そのものが誤っている、という意味である。

なぜここを2つではなく3つに分けたかというと、「データが悪い」ことと「検査の設定が悪い」ことは、対応する人も対応の緊急度もまったく違うからである。データの不備(1)は、入力元の担当者に差し戻して直してもらう話であり、システムの問題ではない。定義ファイルや引数の誤り(2)は、検査の仕組み自体が壊れている話であり、データを送ってきた担当者には何の非もない。この2つを同じ「失敗」として扱ってしまうと、バッチ処理やCIに組み込んだときに、どちらの担当に連絡すべきかがログだけでは分からなくなる。実際に定期実行するバッチの中でこのツールを呼ぶ場合、終了コードによって「1なら差し戻しメールを自動送信」「2なら設定担当に通知」というように、後続の処理を素直に分岐できる。

コード上はif name == "__main__": sys.exit(main())という形で、main()の戻り値がそのままプロセスの終了コードになる。シェルスクリプトからはif python3 csv_validate.py ...; then ...; fiのように、余計な仕組みを足さずそのまま条件分岐に使える設計にしてある。

■ 定義ファイルを先に検査してから、CSVを読みにいく理由

このツールは、CSVを1行も読む前に、まず定義ファイル(ルールJSON)自体の妥当性を検査する。知らないキーが書かれていないか、typeに存在しない型名(たとえば"int"のような綴りの誤り)が指定されていないか、正規表現として壊れたpatternが書かれていないか、といった点をすべて洗い出し、1件でも見つかれば、その時点でCSVには一切触れずに終了コード2で止まる。

この順序にしているのは、定義ファイルの誤りに気づかないまま数万行のCSVを最後まで検査させてしまうと、「検査自体が成立していなかった」という結論に、時間をかけたあとで気づくことになるからである。定義ファイルの検査を最初に独立させておけば、この種の手戻りが起きない。もうひとつの理由は、定義ファイルの誤りとデータの誤りを、報告の時点ではっきり分けるためでもある。定義ファイルの検査で止まったときは、データの行番号は1つも出てこない。データの不備を報告しているのか、検査の仕組み自体が壊れているのかを、出力を見ただけで取り違えないようにしている。

もうひとつ、この定義ファイルの扱いには安全上の理由もある。patternに書かれた正規表現はre.compileに渡すだけで、evalやexecのような、文字列をコードとして実行する仕組みは一切使っていない。定義ファイルは業務によっては他部署や取引先から受け取ることもあり得るが、そうして受け取ったJSONの中に、たとえ悪意のある文字列が書かれていたとしても、それがプログラムとして実行されることはない。定義ファイルはあくまで「データとして読まれるだけ」であり、コードとして解釈される経路を持たせていない。

■ 直す機能をあえて作らなかった理由

「検査だけでなく、ついでに直してくれたら早いのに」と思う人もいるはずで、実際によく聞かれる要望でもある。それでも、このツールには--fixにあたる機能を意図的に作っていない。

自動修正は、結局のところ「本来の正しい値は何か」を機械が推測する行為である。空欄を既定値で埋める、桁あふれの数値を丸める、といった処理は実装自体は難しくないが、その推測が業務の実態と合っているかどうかは、データだけを見ていては分からない。郵便番号の桁数が足りない行があったとして、それが単なる入力ミスで残りの桁を機械的に補ってよいのか、それとも本当に存在しない値が紛れ込んでいて確認が必要なのかは、検査ツールの側からは判断できない。誤った推測で自動的に書き換えてしまうと、間違いが「直った」ように見えたまま気づかれず残ることになり、これは検査結果を放置するより始末が悪い。

そこでこのツールでは、役割を「機械的に判定できることを漏れなく洗い出して報告する」ことだけに絞っている。直すかどうか、どう直すかの判断は、常に人に残す。この線引きのおかげで、ツール自体の設計もひとつ単純になっている。入力したCSVには一切書き込まず、読み込み専用で開く、という単純な安全設計を最後まで崩さずに済んでいる。

■ ツールが無くても手でできる方法

このツールが無くても、表計算ソフトの標準機能だけで、近い考え方をある程度は再現できる。

必須項目のチェックはISBLANK関数で空欄の行を洗い出せる。数値の範囲チェックはAND(値>=下限, 値<=上限)のような式を1列作り、条件を満たさない行だけをオートフィルタで絞り込めばよい。日付の書式チェックは、ISNUMBER(DATEVALUE(値))のような式でエラーになるセルを見つける方法があるが、表計算ソフト側の言語設定によって解釈できる日付書式が変わってしまう点には注意が要る。値の重複チェックはCOUNTIF(対象範囲, 対象セル)が2以上になっている行を探せば見つかる。コード値が決まったリストの中にあるかどうかは、MATCH関数やデータの入力規則のリスト機能を使えば、リストに無い値が入っているセルを見分けられる。

これらの式を検査したい列の数だけ横に並べれば、簡易な検査表は組める。ただし、列が増えるたびに式をコピーする手間が増え、コピーの範囲がずれる事故も起きやすい。正規表現のような柔軟なパターン照合は表計算の標準関数だけでは難しく、複合キー(複数列の組み合わせで重複を見る)も、列を連結してからCOUNTIFをかけるといった一手間が必要になる。「なぜ駄目なのか」という理由の文言も、式ごとに手動で書いておかないと出てこない。ルールの数が少なく、検査を1回か2回で済ませるなら手作業でも十分だが、同じ検査を毎回繰り返す業務であれば、定義ファイルを1つ書いておけば何度でも同じ条件で検査できるこのツールに置き換えたほうが、結果的に速い。

■ 機械可読な出力を分けている理由

このツールは、画面に出す人間向けの報告と、--csvで書き出す機械可読な一覧を、あえて別の出力として用意している。人間向けの報告は「行8 列'quantity' 値='abc': 整数(integer)として解釈できません」のように、1件を1行の文章で読めるようにしてあり、担当者への連絡にそのまま転記できる。一方、機械可読な一覧はrow,column,value,reasonの4列を持つ普通のCSVで、表計算ソフトに読み込んで列名でフィルタしたり、件数を集計したり、別のスクリプトに読ませて後続処理につなげたりできる。

どちらか一方に寄せてしまうと、どちらかの用途で不便が出る。人間向けの文章だけでは機械的な集計がしにくく、機械可読な表だけでは画面でぱっと見て状況を把握しにくい。標準出力には--limit(既定50件)で表示件数の上限を設けているのも、エラーが数百件に達したときに画面が埋め尽くされて逆に読めなくなるのを防ぐためで、その場合も「上位◯件を表示して打ち切りました。総エラー件数◯件」と、打ち切った事実と総件数を必ず明示する。件数だけ黙って切り捨てると、実際にはもっと不備があるのに「これで全部か」と誤解しかねないためである。

■ 検査できないこと

このツールが検査しているのは、あくまでCSVの構造的な要件(必須・型・範囲・文字数・パターン・選択肢・重複・列の存在)であり、業務として正しいデータかどうかまでは判断しない。以下のようなことは、検査の対象外である。

業務的な妥当性は検査できない。数量と単価から計算した金額が別の列の値と一致しているか、在庫数を超えた注文になっていないか、といったビジネスロジックの判定は、このツールの外側にある業務ルールを知っている人か、別の仕組みが担う必要がある。

他システムとの整合性も検査できない。たとえばorder_idのような値が、実際に基幹システム側に存在するかどうかは、このツールが単体で確認できることではない。CSVという1つのファイルの中で完結する条件しか検査できない。

文字コードについては、utf-8-sig→utf-8→cp932の順に自動判定して読み込むが、判定自体が誤っている可能性はゼロではない。判定した文字コードで文法上デコードできてしまえば読み込みは成功するため、見た目の文字化けそのものを検出する機能は無い。区切り文字や改行コードについても、標準のcsvモジュールの既定の挙動に従っており、カンマ区切り・ダブルクォート囲みの一般的なCSVを前提にしている。

「エラーが0件だった」ことは「取り込んで問題ない」ことを意味しない。あくまで定義ファイルに書いた条件を満たしていた、という以上のことは言っていない。取込先の要件が変わったときは、定義ファイルの方も合わせて見直す必要がある。

これらを検査するには、業務ルールを知っている人の目視か、取込先のシステム側の突合機能を別途はさむしかない。「このツールでエラーが出なかったから、あとは全部システム任せでよい」と考えるのではなく、「機械的に判定できる部分はここで先に潰しておき、業務的な判断が要る部分は人の確認に回す」という役割分担として使うのが実態に近い。

■ 検査条件をコードではなく定義ファイル(JSON)にした理由

検査条件をPythonのコードに直接書き込む作り方もできたが、このツールでは条件をJSON形式の定義ファイルという形で分離している。理由は、検査条件を変えるたびにコードを書き換えて動作確認をし直す、という負担を無くしたかったからである。定義ファイルであれば、列を1つ増やしたいときも、コード値の許可リストに1つ値を足したいときも、JSONを数行編集するだけで済み、Pythonの読み書きができない担当者でも、書き方さえ覚えれば自分で条件を調整できる。

取込先の要件は、システムの改修や業務ルールの変更のたびに少しずつ変わっていくものである。検査条件をコードから切り離しておけば、要件が変わるたびに「コードを書き直して、また一から動作確認をする」という工程を踏まずに済む。長く使い続ける前提のツールでは、この分離が地味に効いてくる設計だと考えている。

■ ここから先に入っているもの

無料部分で、「全行を検査してからまとめて報告する」設計の理由、報告を4点セットにした理由、終了コードを0/1/2に分けた理由、定義ファイルを先に検査してevalを使わない理由、直す機能をあえて作らなかった理由、ツールが無くても手でできる方法、検査できないことは、すべて説明した。ここまでの内容だけで、自分の業務に合わせて同じ考え方のスクリプトを書ける人は、この先を購入する必要はない。

ここから先には、実際に手を動かしてすぐ試すための完成品を置いている。

- csv_validate.pyの全文(省略なし。標準ライブラリのみで動く、1ファイルで完結するツール)

- 動作確認用のサンプルCSVと、それに対応する定義ファイル(JSON)。全種類の検査項目を実際に使っている。ダウンロードせず、そのままコピーして試せる

- 実行方法と、自分のデータの列構成に合わせて定義ファイルを書き換える具体的な手順

- 利用条件と免責事項

■ ツール本体(csv_validate.py・全文)