파이썬 자동화 파일 저장 중 깨짐 방지: tempfile·os.replace 안전한 교체 순서

Python 자동화가 JSON·YAML·상태 파일을 덮어쓰는 중 실패해 파일이 깨질 때, 같은 폴더의 임시 파일에 먼저 저장한 뒤 flush·fsync·os.replace를 어떤 순서로 적용하고, 실패 시 원본을 보존할 수 있는지 확인해 보겠습니다. 결론부터 말하면 최종 파일을 직접 열어 덮어쓰기보다 대상과 같은 파일시스템의 임시 파일에 새 내용을 완성한 다음, 필요하면 flush와 fsync를 거쳐 os.replace로 이름을 교체하는 흐름이 안전한 기본값입니다. 다만 이 방식도 여러 프로세스의 동시 작성이나 데이터베이스 수준의 트랜잭션까지 해결하지는 않습니다.

직접 덮어쓰기가 만드는 문제

open(path, "w")나 Path.write_text()로 기존 파일을 바로 열면 새 내용을 쓰는 동안 대상 파일이 중간 상태에 놓일 수 있습니다. 프로세스가 그 순간 종료되거나 쓰기 오류가 발생하면 빈 파일, 앞부분만 남은 파일, 읽을 수 없는 JSON이 다음 실행에 전달될 수 있습니다. 정확한 손상 형태는 파일 크기와 버퍼링, 중단 시점, 파일시스템에 따라 달라지므로 모든 환경에서 같은 결과가 난다고 단정할 수는 없습니다.

핵심은 “새 결과를 만드는 단계”와 “기존 이름을 새 결과로 바꾸는 단계”를 분리하는 것입니다. 임시 파일 쓰기가 실패하면 아직 원본 이름을 건드리지 않았으므로 원본을 유지할 여지가 생깁니다.

같은 폴더에 임시 파일을 만드는 이유

tempfile.mkstemp()는 안전하게 임시 파일을 즉시 만들고 파일 디스크립터와 경로를 돌려줍니다. dir 인자로 위치를 지정할 수 있으므로 최종 파일과 같은 폴더에 만드는 편이 좋습니다. os.replace()는 원본과 대상이 다른 파일시스템에 있으면 실패할 수 있기 때문입니다.

다음 예제는 JSON 직렬화 결과를 임시 파일에 쓰고, 쓰기가 끝난 뒤 최종 경로로 교체합니다. 외부 API를 호출하지 않는 일반적인 저장 예제입니다.

import json
import os
import tempfile
from pathlib import Path
from typing import Any


def atomic_write_json(path: str | Path, data: Any) -> None:
    target = Path(path)
    target.parent.mkdir(parents=True, exist_ok=True)
    fd, temporary_name = tempfile.mkstemp(
        dir=target.parent,
        prefix=f".{target.name}.",
        suffix=".tmp",
    )

    try:
        with os.fdopen(fd, "w", encoding="utf-8") as temporary_file:
            json.dump(data, temporary_file, ensure_ascii=False, indent=2)
            temporary_file.flush()
            os.fsync(temporary_file.fileno())

        os.replace(temporary_name, target)
    except Exception:
        try:
            os.unlink(temporary_name)
        except FileNotFoundError:
            pass
        raise

mkstemp()가 반환한 디스크립터는 os.fdopen()으로 파일 객체로 바꿉니다. json.dump()가 예외를 내거나 flush()·fsync()·os.replace() 중 하나가 실패하면 예외를 다시 올리고, 아직 남아 있는 임시 파일을 정리합니다. os.replace()가 성공하면 임시 경로는 대상 이름으로 바뀌므로 뒤늦게 임시 경로를 삭제하려 하지 않습니다.

flush, fsync, os.replace의 순서

세 호출은 비슷해 보이지만 책임이 다릅니다.

1. flush()는 Python의 버퍼에 남아 있는 내용을 파일 객체에서 운영체제 쪽으로 넘기도록 요청합니다.
2. os.fsync()는 파일 디스크립터의 쓰기를 디스크에 반영하도록 요청합니다. 버퍼링된 파일 객체를 사용했다면 먼저 flush()한 뒤 호출해야 합니다.
3. os.replace()는 준비된 임시 파일을 대상 이름으로 교체합니다. 대상이 이미 있으면 교체하고, POSIX에서는 성공한 rename이 원자적 교체로 동작합니다.

따라서 일반적인 순서는 내용 작성 → flush → fsync → 파일 닫기 → os.replace입니다. os.replace()가 성공했다는 사실만으로 모든 플랫폼에서 디렉터리 엔트리까지 영구 저장됐다고 일반화할 수는 없습니다. 크래시 이후의 영속성까지 엄격하게 보장해야 한다면 운영체제와 파일시스템별 디렉터리 동기화 절차를 별도로 검토해야 합니다.

실패하면 원본은 어떻게 남나

임시 파일에 쓰는 동안 실패하면 os.replace()에 도달하지 않으므로 기존 대상 파일은 그 절차에서 교체되지 않습니다. 예외 처리에서 임시 경로만 지우고 예외를 다시 올리는 이유가 여기에 있습니다. 호출부가 오류를 숨기면 자동화는 실패했는데도 성공한 것처럼 다음 단계로 진행할 수 있으니, 로그를 남기거나 재시도 정책으로 연결하는 것이 좋습니다.

반대로 os.replace() 자체가 실패하면 원본이 그대로 남는다고 모든 파일시스템에서 단정하기보다, 실패 원인과 환경을 확인해야 합니다. 대상과 임시 파일이 다른 파일시스템에 있거나 권한이 부족한 경우가 대표적인 점검 대상입니다.

이 방식으로 해결되지 않는 범위

동시 작성

os.replace()는 한 번의 이름 교체를 원자적으로 수행할 수 있지만, 여러 프로세스가 같은 상태 파일을 읽고 각자 새 파일을 만들어 교체하는 전체 순서를 조정하거나 잠가 주지는 않습니다. 두 작업이 동시에 시작되면 마지막 교체가 앞선 결과를 덮는 lost update가 생길 수 있습니다. 동시 작성이 가능하다면 파일 잠금, 단일 writer, 버전 확인 같은 별도 정책을 먼저 정해야 합니다.

심볼릭 링크

POSIX rename() 계열의 규칙에서는 마지막 경로 구성요소가 심볼릭 링크일 때 링크의 대상이 아니라 링크 자체를 대상으로 삼습니다. 따라서 운영 환경에서 대상 경로가 심볼릭 링크일 수 있다면, “링크가 가리키는 파일을 갱신한다”는 기대와 실제 교체 결과가 다를 수 있습니다. 링크를 허용할지, 실제 경로를 명시할지 운영 규칙으로 정해 두는 편이 안전합니다.

파일시스템 경계와 데이터베이스 요구

임시 파일을 다른 마운트나 파일시스템에 두면 os.replace()가 실패할 수 있습니다. 또 한 파일의 최신 스냅샷 교체가 아니라 여러 레코드의 일관성, 복구 로그, 동시 트랜잭션이 필요하다면 단순 파일 교체만으로는 부족할 수 있습니다. 그때는 SQLite나 WAL 같은 저장 방식을 요구사항과 운영 환경에 맞춰 비교해야 합니다.

적용 전 확인 순서

저라면 자동화에 적용하기 전에 다음을 확인합니다.

• 최종 파일과 임시 파일이 같은 디렉터리와 파일시스템에 있는가?
• 새 내용을 임시 파일에서 끝까지 만들고, 직렬화 오류를 os.replace() 전에 감지하는가?
• flush() 뒤에 os.fsync()를 호출해야 하는 영속성 요구가 있는가?
• 모든 예외 경로에서 임시 파일을 정리하고 실패를 호출부에 전달하는가?
• 같은 파일을 여러 프로세스가 쓸 수 있는가? 그렇다면 잠금이나 단일 writer 정책이 있는가?
• 대상 경로가 심볼릭 링크일 수 있는가? 링크 자체를 교체해도 되는가?

이 조건이 맞으면 단순한 설정·상태·결과 파일에는 임시 파일과 os.replace()가 직접 덮어쓰기보다 판단하기 쉬운 기본 선택이 됩니다. 반면 동시성이나 복구 요구가 커지면 파일 교체 코드를 조금 더 늘리는 것보다 저장소 자체를 바꾸는 편이 맞을 수 있습니다.

정리

파이썬 자동화 파일 저장 중 깨짐을 줄이는 기본 순서는 같은 폴더에 임시 파일을 만들고, 새 내용을 작성한 뒤 flush()와 os.fsync()를 적용하고, 파일을 닫은 다음 os.replace()로 최종 이름을 교체하는 것입니다. 예외가 나면 임시 파일만 정리하고 원본을 유지할 수 있습니다. 다만 동시 작성 제어, 심볼릭 링크의 의미, 크래시 이후 디렉터리 영속성, 데이터베이스 수준의 일관성은 별도 문제로 남습니다.

다음으로는 여러 프로세스가 같은 상태 파일을 동시에 쓸 때 충돌을 어떻게 줄일지, 심볼릭 링크 대상에서 os.replace()가 어떤 결과를 내는지, 파일 저장 대신 SQLite나 WAL을 선택할 기준을 각각 분리해 검토하면 됩니다.

참고한 공식 자료

• Python os 공식 문서 — flush() 이후 os.fsync()를 호출하는 흐름과 os.replace()의 동작을 확인했습니다.
• Python tempfile 공식 문서 — mkstemp()와 임시 파일 생성 위치를 확인했습니다.
• POSIX rename() 명세 — 심볼릭 링크, 원자적 교체, 동시 작성 제어의 범위를 확인했습니다.
• POSIX 일반 개념 — 원자적 작업과 크래시 뒤 영속성의 차이를 확인했습니다.