Pythonで設定ファイルを安全に更新する:一時ファイルとos.replaceの使い分け

Python

この記事について
この記事は、生成AIを活用した自動生成フローで作成しています。Python公式のtempfileとos.replaceの仕様を参照し、設定ファイルを途中まで書いた状態で残さないための考え方を整理しました。掲載コードの実行は未確認です。

検証ステータス:📘 公式仕様を参照・掲載コードの実行は未確認

Pythonで設定ファイルを安全に更新する:一時ファイルとos.replaceの使い分け

設定ファイルを上書き保存する途中でプログラムが停止すると、ファイルが空になったり、途中までしか書かれていなかったりすることがあります。たとえば、毎朝バッチが参照するJSON設定を更新する処理で、書込み途中に例外が起きると、翌日のバッチまで起動できなくなるかもしれません。そこで、新しい内容を別ファイルへ書き終えてから、最後に名前を置き換える方法を考えます。

直接上書きのどこが危ないのか

open(path, "w")は、既存ファイルを開く時点で内容を切り詰めます。その後のwrite()が途中で失敗すると、以前の正常な内容は戻りません。JSONが途中で途切れていても、書込み処理自体が始まった事実は消えません。更新前にバックアップを取る方法もありますが、日常の小さな設定更新では、まず旧ファイルを触らない手順を設計する方が分かりやすいでしょう。

この問題は「保存した後にJSONが正しいか」だけでは解決しません。保存途中で読む別プロセスに何が見えるか、失敗したとき旧ファイルを維持できるか、という二つの問いを分ける必要があります。

対象環境と試す範囲

Python 3の標準ライブラリだけを使います。追加パッケージ、ネットワーク、管理者権限は不要です。作業場所は実験用の一時ディレクトリであり、実際の業務設定やWordPressのファイルは変更しません。Windows、Linux、macOSで同じ設計を考えられますが、OSやファイルシステムによって置換の制約は異なります。各OSでの実行確認はしていません。

以下の例では、書込み先と同じディレクトリ内に一時ファイルを作ります。別ドライブや別マウントへ移動する場合には、原子的な名前の置換を期待できません。原子的とは「名前の切替えが途中状態を見せない」という意味であり、停電後の永続性まで保証する言葉ではありません。

まず架空のJSONを更新する

次のコードは実験用ディレクトリを作り、最初に旧設定を保存してから新設定へ置き換えます。更新後にはファイルを読み直して、想定した値になったかを確認します。

import json
import os
import tempfile
from pathlib import Path

with tempfile.TemporaryDirectory() as work:
    target = Path(work) / "settings.json"
    target.write_text('{"mode":"old"}\n', encoding="utf-8")

    # 一時ファイルは必ず置換先と同じディレクトリに作る

    temp_name = None
    try:
        with tempfile.NamedTemporaryFile(
            mode="w", encoding="utf-8", newline="\n",
            dir=target.parent, prefix=".settings-", suffix=".tmp",
            delete=False,
        ) as fp:
            temp_name = fp.name
            json.dump({"mode": "new"}, fp, ensure_ascii=False)
            fp.write("\n")
            fp.flush()
            os.fsync(fp.fileno())

        # 書込み完了後に初めて公開先の名前を切り替える

        os.replace(temp_name, target)
        temp_name = None
        print(json.loads(target.read_text(encoding="utf-8")))
    finally:

        # 置換前に失敗したときだけ残った一時ファイルを片付ける

        if temp_name is not None:
            try:
                os.unlink(temp_name)
            except FileNotFoundError:
                pass

期待される表示(未実行)は{'mode': 'new'}です。TemporaryDirectoryは実験終了時に作業ディレクトリを削除します。したがって、実験後に実ファイルが残らないことも、この例の安全上の特徴です。書込み先を自分の本番設定に変えて試す前に、まずこの架空の例で処理の順序を理解してください。

なぜ一時ファイルを同じ場所に作るのか

NamedTemporaryFileは、後から名前で指定できる一時ファイルを作ります。delete=Falseとしたのは、ファイルを閉じた後でos.replaceに渡すためです。特にWindowsでは、開いたままのファイルの名前を変更できない条件があるので、withを抜けて閉じてから置換する形にしています。

json.dumpはPythonの辞書をJSONテキストに変換します。flush()はPython側のバッファに残るデータを下位層へ送り、os.fsync()は可能な範囲でファイル内容をストレージへ反映するよう要求します。ただし、これだけでディレクトリの更新や停電時の耐久性が全環境で保証されるわけではありません。

最後のos.replaceが重要です。新しいファイルの内容ができてから、公開先のパスを新しいファイルへ切り替えます。置換前に例外が起きれば、通常は旧ファイルをそのまま残せます。finallyでは途中で残った一時ファイルを片付けますが、os.replaceが成功した後はtemp_name = Noneにして、新しい本体を誤って削除しないようにしています。

1条件だけ変えて失敗を観察する

実験用コードのos.replace(temp_name, target)の直前に、raise RuntimeError("simulated failure")を追加してみてください。期待される結果は例外の発生です。置換が実行されないので、旧ファイルは変更されない設計です。ただし、掲載コードのままではTemporaryDirectoryが終了時に実験ファイルを消すため、旧ファイルの内容を目で確認したければ、例外を捕捉してtarget.read_text()を表示する処理を同じwithブロック内に追加してください。

ここで比較したいのは「例外が出るか」ではありません。直接上書きなら既存内容を消した後に失敗する可能性があるのに対し、一時ファイル方式なら公開先に触る前に失敗できる点です。置換後の処理で失敗した場合は、すでに新しい内容になっているため、旧版へ自動的に戻るわけではありません。この境界を誤解すると、失敗時に必ずロールバックされる仕組みだと過信してしまいます。

失敗時の切り分け

PermissionErrorなら、対象ディレクトリへの作成権限と既存ファイルの置換権限を分けて調べます。一時ファイルの作成には成功しても、置換時に権限や他プロセスの使用状況で失敗する場合があります。Windowsでは、対象ファイルを別アプリが開いている条件も確認してください。

OSErrorが発生したら、空き容量、ファイルシステム、マウントの境界、対象パスの存在、同名ファイルの種類を確認します。os.replaceは、ディレクトリをファイルとして置き換えるなど、あらゆる組み合わせを許すわけではありません。例外を握りつぶして成功と表示するのは避け、元ファイルと一時ファイルの状態を確認できるようにします。

また、更新内容が正しいJSONであることと、業務ルール上正しい設定であることは別問題です。json.loadsで構文を確かめられても、必須キーが欠けている、値の範囲が違う、参照先が存在しない、といった不整合は別途検査が必要です。重要な設定では、置換前に新しい一時ファイルを読み直して検証する工程を追加すると、誤った内容を公開する可能性を下げられます。

業務で使うときの判断

毎朝のジョブが参照する設定、定期集計の中間成果、静的なJSONキャッシュなど、読み手が完成した一つのファイルを期待する用途で、この方式は有効です。ただし、複数の書き手が同時に更新すると、後から置換した方が先の変更を上書きします。原子的な置換は同時更新の競合制御ではありません。複数プロセスから書くなら、ロックやバージョン照合を別に設計する必要があります。

既存ファイルのアクセス権や所有者などの属性を保ちたい場合にも注意が必要です。一時ファイルを置換すると、以前のファイルと同じ属性が自動で引き継がれるとは限りません。設定ファイルの所有者、パーミッション、ACLを確認し、更新後の状態をテストしてください。セキュリティ上重要な設定では、この点を省略してはいけません。

最後に、原子的な置換と耐障害性は同義ではないと覚えておきましょう。プロセスの例外に備える設計としては有用ですが、停電、ストレージ故障、ネットワークファイルシステム、複数ファイルを一括で更新する処理まで保証するものではありません。業務導入ではバックアップ、読戻し、監視、復旧手順を別に確認します。

公式情報・一次資料

掲載コードの実行とOS別の挙動確認は未実施です。公式仕様を参照した説明と、期待される動作を区別して記載しています。

文書情報

記事タイトル
Pythonで設定ファイルを安全に更新する:一時ファイルとos.replaceの使い分け
作成日
更新日
Source URL
https://papanda925.com/?p=18635

ライセンス: 本記事のうち、当サイトが権利を有する本文・自作図表は、特記なき限り CC BY 4.0 で利用できます。生成AIを活用して作成・編集した内容を含みます。コードについて、別途ライセンス表示またはリンク先GitHubリポジトリのライセンスがある場合は、その条件を優先します。引用・第三者資料・画像・商標等は本ライセンスの対象外です。 利用ポリシー

タイトルとURLをコピーしました