導入 — つまずきに寄り添う短い前置き
実務でCSVやJSONを扱うと、エンコーディング不一致、途中で止まった書き込み、欠損データ、同時実行による破損といった問題に直面します。小さなスクリプトでもこれらを放置すると運用で大きな手戻りになります。本記事では「一人でも回す」ことを目的に、標準ライブラリだけで組める安全なファイル入出力のパターンと、現場で役立つチェックリストをテンプレート付きでまとめます。
基本パターン：pathlib と with を使う理由
まずは基本の抑えどころ。Pathlibはパス操作を読みやすくし、withはリソース解放を保証します。エンコーディングは明示的に指定しましょう。
簡単な読み書きの例
実装メモ: コード例は環境に合わせて調整してください。例: from pathlib import Path
CSV の読み書き（csv.reader / DictReader）
小さなCSVなら一括読みでも良いですが、実務では行数不明・大きめファイルが多いため逐次処理（ストリーム処理）を基本にします。ヘッダーの有無や型変換に注意してください。
行単位処理の例（DictReader）
実装メモ: コード例は環境に合わせて調整してください。例: import csv
チャンク処理の考え方
大きいファイルは、固定行数ごとにバッチ処理して中間出力を作ると堅牢です。メモリ不足や途中障害からの復帰が容易になります。
| シナリオ | 推奨パターン |
|---|---|
| 小〜中サイズ | 逐次処理（DictReader） |
| 大サイズ | チャンク（行数で分割）→中間ファイルに保存 |
| 欠損多いデータ | 行ごとの簡易検証→不正行は別ファイルへ |
JSON／メタデータ保存
実行ログや処理メタデータはJSONで保存すると取り回しが良く、履歴管理や不具合解析がしやすくなります。保存時はensure_asciiやindentを適宜指定します。
実装メモ: コード例は環境に合わせて調整してください。例: import json
安全な書き込み：一時ファイル→原子置換
直接上書きすると途中で失敗したときファイルが壊れます。一時ファイルに書いてから置換（移動）するのが基本です。Windows/Linuxでの挙動差に注意し、可能ならPath.replace()やshutil.moveを使います。
テンプレート（安全な書き込み）
実装メモ: コード例は環境に合わせて調整してください。例: import tempfile
例外処理とリトライ方針
例外は「捕まえて通知→回復可能ならリトライ→不可能ならロールバック／通知」で設計します。ファイルI/OではIOError系、エンコーディングエラー、CSVのパース例外を想定します。
単純なリトライ例
実装メモ: コード例は環境に合わせて調整してください。例: import time
ログ出力と最小限の検証（簡易チェック）
logging を使い、処理前後で簡易チェック（行数、ヘッダー整合、サンプル検証）を行う習慣をつけます。ログは運用での原因追跡に必須です。
実装メモ: コード例は環境に合わせて調整してください。例: import logging
| チェック項目 | 目的 |
|---|---|
| エンコーディング確認 | 文字化けや読み飛ばし防止 |
| ヘッダー整合 | 列位置ずれを検出 |
| 行数の前後比較 | 欠落や重複の発見 |
コードテンプレート集（最小限の実務スクリプト）
以下は「CSVを安全に取り込み、簡単な前処理をして結果とメタを原子的に保存する」最小テンプレートです。実務ではこの中にドメイン固有の検証を追加します。
実装メモ: コード例は環境に合わせて調整してください。例: #!/usr/bin/env python3
実務チェックリスト
| 項目 | 確認ポイント |
|---|---|
| エンコーディング | 入力のencodingを明示（utf-8推奨）、errors=’replace’で観察ログを確認 |
| ヘッダー整合 | 期待列が揃っているか、不要列がないか確認 |
| 部分書き込み対策 | 一時ファイル→移動で原子置換にする |
| 同時実行回避 | 簡易ロック（PIDファイル）やワークディレクトリ分離を採用 |
| 大ファイル対策 | チャンク処理・中間ファイル出力・最大メモリ確認 |
| テスト | 小ファイルで欠損・エンコーディングエラー・途中停止を再現して確認 |
まとめ
本記事では「安全な」ファイル入出力の基礎パターンを、CSV読み込み→前処理→安全な書き出し→メタ保存という実務ワークフローに沿ってまとめました。ポイントは（1）明示的なエンコーディング指定、（2）with / pathlib の活用、（3）一時ファイルを使った原子置換、（4）ログと簡易検証、（5）例外・リトライ設計です。
次の一歩：この記事のテンプレートを使って、まずはローカルで「安全なCSV取込スクリプト」を動かし、欠損・エンコーディング・部分書き込みの異常ケースを再現して対処法を確認してください。次回はこの基礎を元に、pandasを使った高速処理やメモリ節約のテクニックに進みます。
シリーズ：AIとPythonの実務 — Manage AI