From c453ee288a91bbc7128737f2c9ca35b21affa5d1 Mon Sep 17 00:00:00 2001 From: Boris Kozak Date: Mon, 16 Nov 2026 16:26:03 +0000 Subject: [PATCH 1/2] fsync the temporary .env file before replacing it rewrite() wrote the new contents to a temporary file and renamed it over the target without fsync, so a power loss shortly after set_key or unset_key returned could leave behind an empty or garbage .env. Flush and fsync the temporary file while it is still open, and best-effort fsync the containing directory on POSIX so the rename itself is durable. Directory fsync failures are ignored. A flush or fsync failure still discards the temporary file and reports the original error. Fixes #713 --- src/dotenv/main.py | 59 ++++++++++++++++++++--- tests/test_main.py | 118 ++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 168 insertions(+), 9 deletions(-) diff --git a/src/dotenv/main.py b/src/dotenv/main.py index 5faa7f0e..2522bf99 100644 --- a/src/dotenv/main.py +++ b/src/dotenv/main.py @@ -158,6 +158,28 @@ def _discard_temp_file(path: pathlib.Path) -> None: logger.warning("python-dotenv could not remove the temporary file %s", path) +def _fsync_directory(path: StrPath) -> None: + """ + Best-effort fsync of the directory containing `path` (POSIX only). + + Makes the rename performed by `rewrite` itself durable. Any failure is + ignored: the file contents are already on disk at this point, and some + filesystems reject directory fsync. + """ + if os.name != "posix": + return + try: + dir_fd = os.open(os.path.dirname(os.path.abspath(path)), os.O_RDONLY) + except OSError: + return + try: + os.fsync(dir_fd) + except OSError: + pass + finally: + os.close(dir_fd) + + @contextmanager def rewrite( path: StrPath, @@ -197,14 +219,34 @@ def rewrite( err.filename = os.fspath(path) raise - with temp_file as dest: - dest_path = pathlib.Path(dest.name) - error = None - - try: - with source: - yield (source, dest) - except BaseException as err: + error = None + try: + with temp_file as dest: + dest_path = pathlib.Path(dest.name) + + try: + with source: + yield (source, dest) + except BaseException as err: + error = err + + if error is None: + # Flush the new contents to the OS and force them to disk + # before the rename, while the file is still open. Otherwise + # a power loss or kernel crash shortly after the rename + # could leave behind an empty or garbage .env. + try: + dest.flush() + os.fsync(dest.fileno()) + except BaseException as err: + # Route through the shared cleanup below so the + # temporary file is discarded instead of left behind. + error = err + except BaseException as err: + # A failure closing the temporary file must not skip the cleanup + # below: close() re-attempts the flush, so a persistent flush + # error is raised again here. Keep the original error. + if error is None: error = err if error is None: @@ -216,6 +258,7 @@ def rewrite( except BaseException: _discard_temp_file(dest_path) raise + _fsync_directory(path) else: _discard_temp_file(dest_path) raise error from None diff --git a/tests/test_main.py b/tests/test_main.py index 930ab171..fcae728a 100644 --- a/tests/test_main.py +++ b/tests/test_main.py @@ -11,7 +11,7 @@ import pytest import dotenv -from dotenv.main import DotEnv +from dotenv.main import DotEnv, _fsync_directory def test_set_key_no_file(tmp_path): @@ -275,6 +275,122 @@ def windows_read_only_semantics(path): return path.exists() and not path.stat().st_mode & stat.S_IWUSR +@pytest.mark.parametrize( + "rewrite", + [ + lambda path: dotenv.set_key(path, "a", "y"), + lambda path: dotenv.unset_key(path, "a"), + ], + ids=["set_key", "unset_key"], +) +def test_rewrite_fsyncs_before_replace(tmp_path, rewrite): + dotenv_path = tmp_path / ".env" + dotenv_path.write_text("a=x\n") + calls = [] + real_fsync = os.fsync + real_replace = os.replace + + def fsync(fd): + calls.append("fsync") + return real_fsync(fd) + + def replace(src, dst): + calls.append("replace") + return real_replace(src, dst) + + with mock.patch("dotenv.main.os.fsync", side_effect=fsync): + with mock.patch("dotenv.main.os.replace", side_effect=replace): + rewrite(dotenv_path) + + assert calls.index("fsync") < calls.index("replace") + + +def test_rewrite_ignores_directory_fsync_failure(tmp_path, monkeypatch): + def failing_open(*args, **kwargs): + raise OSError("directory fsync not supported") + + monkeypatch.setattr(os, "open", failing_open) + _fsync_directory(tmp_path / ".env") + + +def test_rewrite_ignores_directory_fsync_error(tmp_path): + calls = [] + + def failing_fsync(fd): + calls.append(fd) + raise OSError("EINVAL: directory fsync not supported") + + with mock.patch("dotenv.main.os.fsync", side_effect=failing_fsync): + _fsync_directory(tmp_path / ".env") + + assert len(calls) == 1 + + +@pytest.mark.parametrize( + "rewrite", + [ + lambda path: dotenv.set_key(path, "a", "y"), + lambda path: dotenv.unset_key(path, "a"), + ], + ids=["set_key", "unset_key"], +) +@pytest.mark.parametrize("failure", ["flush", "fsync"]) +def test_rewrite_flush_or_fsync_failure_leaves_no_temp_file(tmp_path, rewrite, failure): + dotenv_path = tmp_path / ".env" + dotenv_path.write_text("a=x\n") + + if failure == "fsync": + patch = mock.patch("dotenv.main.os.fsync", side_effect=OSError("EIO")) + else: + # TextIOWrapper.flush can't be patched (immutable type), so fail + # the flush by substituting a file whose flush() and close() + # both raise, as a real persistent flush failure would. + def failing_factory(*args, **kwargs): + return _FlushFailingFile(tmp_path / ".tmp_flushfail") + + fake_tempfile = mock.Mock() + fake_tempfile.NamedTemporaryFile = failing_factory + patch = mock.patch("dotenv.main.tempfile", fake_tempfile) + + with patch: + with pytest.raises(OSError): + rewrite(dotenv_path) + + assert dotenv_path.read_text() == "a=x\n" + assert list(tmp_path.iterdir()) == [dotenv_path] + + +class _FlushFailingFile: + """Stand-in for NamedTemporaryFile whose flush() fails persistently. + + Like a real TextIOWrapper, close() re-attempts the flush and raises + again, so the `with` block exit also raises. + """ + + def __init__(self, name): + self.name = str(name) + self._buf = io.StringIO() + + def write(self, data): + return self._buf.write(data) + + def flush(self): + raise OSError("ENOSPC") + + def close(self): + raise OSError("ENOSPC") + + def fileno(self): + raise OSError("ENOSPC") + + def __enter__(self): + return self + + def __exit__(self, *exc): + self.close() + return False + + @pytest.mark.parametrize( "rewrite", [ From 06c32e1d1e1158585db29e50632a415f211475f7 Mon Sep 17 00:00:00 2001 From: Boris Kozak Date: Wed, 18 Nov 2026 16:01:30 +0000 Subject: [PATCH 2/2] test: skip POSIX-only directory fsync tests on Windows, fix mypy patch typing The directory-fsync tests assert on os.fsync calls, but _fsync_directory returns early on non-POSIX platforms, so the calls never happen on Windows. Skip them there. Annotate the patcher in the flush/fsync failure test as AbstractContextManager[Any]: the two mock.patch call shapes return incompatible _patch generics and mypy 3.13 rejects the reassignment. --- tests/test_main.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/tests/test_main.py b/tests/test_main.py index fcae728a..2444995e 100644 --- a/tests/test_main.py +++ b/tests/test_main.py @@ -6,6 +6,8 @@ import subprocess import sys import textwrap +from contextlib import AbstractContextManager +from typing import Any from unittest import mock import pytest @@ -305,6 +307,7 @@ def replace(src, dst): assert calls.index("fsync") < calls.index("replace") +@pytest.mark.skipif(os.name != "posix", reason="directory fsync is POSIX-only") def test_rewrite_ignores_directory_fsync_failure(tmp_path, monkeypatch): def failing_open(*args, **kwargs): raise OSError("directory fsync not supported") @@ -313,6 +316,7 @@ def failing_open(*args, **kwargs): _fsync_directory(tmp_path / ".env") +@pytest.mark.skipif(os.name != "posix", reason="directory fsync is POSIX-only") def test_rewrite_ignores_directory_fsync_error(tmp_path): calls = [] @@ -340,7 +344,9 @@ def test_rewrite_flush_or_fsync_failure_leaves_no_temp_file(tmp_path, rewrite, f dotenv_path.write_text("a=x\n") if failure == "fsync": - patch = mock.patch("dotenv.main.os.fsync", side_effect=OSError("EIO")) + patch: AbstractContextManager[Any] = mock.patch( + "dotenv.main.os.fsync", side_effect=OSError("EIO") + ) else: # TextIOWrapper.flush can't be patched (immutable type), so fail # the flush by substituting a file whose flush() and close()