atomic-save 0.0.0

A tool that guarantees fully intact files by writing them atomically.

English description follows Japanese.

atomic-save

概要

• atomic-save は、ファイルを 破損させない安全な保存 を実現する Python の小型ツールです。
• 保存途中にプログラムが落ちても、ファイルは 完全に書き込まれた状態 か 保存前の状態 のどちらかになります。

使い方の例

import atomic_save

# 文字列を atomic に保存
atomic_save["./testfile.txt"] = "hello!"

# バイト列を atomic に保存
atomic_save["./testfile.txt"] = b"hello!"

動作原理

データはまず 一時ファイル に完全に書き込まれます。 その後、書き込みが正常終了した段階で、一時ファイルが元ファイルと atomic に置き換え られます。 これにより、途中まで書かれた壊れたファイルが残ることはありません。

• 一時ファイル名の形式: <元ファイル名>.<6桁16進ランダム>.atomic_save_temp
• 保存できる型: str（文字列）, bytes（バイト列）
• 元ファイルが存在しない場合も問題なく保存可能 途中で落ちても「元々ファイルがなかった状態」に戻ります。

保存後の読み込みは通常どおり open() で行ってください。 成功した保存結果は常に元のファイル名に収まります。

---

atomic-save

Overview

• atomic-save is a lightweight Python utility that guarantees corruption-free file writing.
• Even if a crash occurs mid-save, the file will end up either fully written or completely unchanged.

Usage Example

import atomic_save

# Save text atomically
atomic_save["./testfile.txt"] = "hello!"

# Save bytes atomically
atomic_save["./testfile.txt"] = b"hello!"

How It Works

atomic-save writes all data into a temporary file first. After the write finishes successfully, it atomically replaces the original file with the completed temporary file. This design ensures no partially written file ever appears.

• Temporary file format: <original_filename>.<6-digit hex random>.atomic_save_temp
• Allowed value types: str, bytes
• When the original file does not exist, saving works normally. If a crash occurs, the state cleanly falls back to “file did not exist.”

Reading the file requires no special API—just open the file normally. If the save succeeds, the completed data always appears under the original name.