kitsuyui.fileio 0.8.1__tar.gz

kitsuyui_fileio-0.8.1/LICENSE

@@ -0,0 +1,11 @@
+Copyright 2023-2025 Kitsu Yui
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

kitsuyui_fileio-0.8.1/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: kitsuyui.fileio
+Version: 0.8.1
+Summary: Explicit and safe file writing utilities
+Author-email: Yui KITSU <kitsuyui+github@kitsuyui.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/kitsuyui/pypi-playground
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# kitsuyui.fileio
+
+Small, explicit file I/O primitives. The first release provides atomic
+replacement of a single file without runtime dependencies (Python 3.10+).
+
+```python
+from kitsuyui.fileio import atomic_write, atomic_write_bytes, atomic_write_text
+
+atomic_write_text("settings.txt", "ready\n")
+atomic_write_bytes("data.bin", b"\x00\x01")
+with atomic_write("large.bin") as output:
+    output.write(b"first chunk")
+    output.write(b"second chunk")
+```
+
+`atomic_write` yields a binary stream. On normal exit it flushes and closes the
+stream before replacing the destination. An exception inside the block leaves
+the destination untouched and removes the temporary file when possible. Do not
+close the yielded stream manually. The convenience functions accept paths and
+bytes or text respectively; text is encoded as UTF-8 unless specified otherwise.
+The parent directory must already exist. A caller that wraps the binary stream
+in a `TextIOWrapper` must flush and detach the wrapper before leaving the block;
+closing the supplied stream causes a `ValueError` and cancels replacement.
+Text convenience writes use `str.encode` and do not translate newlines; callers
+may choose the encoding and encoding error handler.
+
+## Guarantees and boundaries
+
+The temporary file is created in the destination directory and installed with
+`os.replace`. On a filesystem supporting POSIX atomic rename, a reader opening
+the destination sees either the previous file or the complete new file during
+normal execution; an
+already-open descriptor may continue to refer to the old file. On other systems
+and filesystems, replacement guarantees depend on the platform. This does not
+lock writers, prevent lost updates, make multiple replacements transactional, or
+secure a directory controlled by an untrusted party. Concurrent successful
+writers are last-replacement-wins. A destination symlink itself is replaced;
+its target is not modified. The temporary file is created with restrictive
+permissions (0600 on POSIX). Existing ownership, permissions, timestamps, ACLs,
+extended attributes and hard links are not preserved. The restrictive default
+avoids silently exposing content from a private file or temporary write. To
+choose another POSIX permission mode, pass `permissions=0o644` (for example);
+the specified bits are applied to the temporary file before replacement and
+are not filtered by umask. Do not use permissive modes for sensitive data. On
+Windows `os.chmod` has limited permission semantics. Copying existing permissions
+is deliberately left to the caller because metadata and access policy are
+platform-specific and can change concurrently.
+
+The keyword `durability` distinguishes visibility from persistence:
+
+* `"none"`: flush and close before replacement; no `fsync`.
+* `"file"` (default): also `fsync` the staged file before replacement.
+* `"file_and_directory"`: also `fsync` the parent directory after replacement.
+  This option is available only on POSIX and can still fail on a filesystem
+  that does not support directory sync.
+
+Sync calls request persistence from the operating system; they cannot guarantee
+the behavior of every filesystem, storage device, or hardware buffer. A failure
+before `os.replace` leaves an existing destination unchanged. If directory
+sync fails after replacement, `DurabilityError` is raised: the new destination
+is already visible, but its persistence is uncertain. If replacement itself fails,
+the operating system error is propagated. Abrupt process termination can leave a
+temporary file behind; ordinary exception cleanup is best effort. A crash with
+`"none"` can leave the new file empty or truncated even after the rename, so
+the runtime visibility guarantee is not a crash-recovery guarantee. On macOS,
+`os.fsync` does not request the stronger `F_FULLFSYNC` operation, so even a
+successful sync does not guarantee that hardware buffers reached durable media.
+
+## License
+
+BSD 3-Clause License. See the repository's LICENSE.

kitsuyui_fileio-0.8.1/README.md

@@ -0,0 +1,71 @@
+# kitsuyui.fileio
+
+Small, explicit file I/O primitives. The first release provides atomic
+replacement of a single file without runtime dependencies (Python 3.10+).
+
+```python
+from kitsuyui.fileio import atomic_write, atomic_write_bytes, atomic_write_text
+
+atomic_write_text("settings.txt", "ready\n")
+atomic_write_bytes("data.bin", b"\x00\x01")
+with atomic_write("large.bin") as output:
+    output.write(b"first chunk")
+    output.write(b"second chunk")
+```
+
+`atomic_write` yields a binary stream. On normal exit it flushes and closes the
+stream before replacing the destination. An exception inside the block leaves
+the destination untouched and removes the temporary file when possible. Do not
+close the yielded stream manually. The convenience functions accept paths and
+bytes or text respectively; text is encoded as UTF-8 unless specified otherwise.
+The parent directory must already exist. A caller that wraps the binary stream
+in a `TextIOWrapper` must flush and detach the wrapper before leaving the block;
+closing the supplied stream causes a `ValueError` and cancels replacement.
+Text convenience writes use `str.encode` and do not translate newlines; callers
+may choose the encoding and encoding error handler.
+
+## Guarantees and boundaries
+
+The temporary file is created in the destination directory and installed with
+`os.replace`. On a filesystem supporting POSIX atomic rename, a reader opening
+the destination sees either the previous file or the complete new file during
+normal execution; an
+already-open descriptor may continue to refer to the old file. On other systems
+and filesystems, replacement guarantees depend on the platform. This does not
+lock writers, prevent lost updates, make multiple replacements transactional, or
+secure a directory controlled by an untrusted party. Concurrent successful
+writers are last-replacement-wins. A destination symlink itself is replaced;
+its target is not modified. The temporary file is created with restrictive
+permissions (0600 on POSIX). Existing ownership, permissions, timestamps, ACLs,
+extended attributes and hard links are not preserved. The restrictive default
+avoids silently exposing content from a private file or temporary write. To
+choose another POSIX permission mode, pass `permissions=0o644` (for example);
+the specified bits are applied to the temporary file before replacement and
+are not filtered by umask. Do not use permissive modes for sensitive data. On
+Windows `os.chmod` has limited permission semantics. Copying existing permissions
+is deliberately left to the caller because metadata and access policy are
+platform-specific and can change concurrently.
+
+The keyword `durability` distinguishes visibility from persistence:
+
+* `"none"`: flush and close before replacement; no `fsync`.
+* `"file"` (default): also `fsync` the staged file before replacement.
+* `"file_and_directory"`: also `fsync` the parent directory after replacement.
+  This option is available only on POSIX and can still fail on a filesystem
+  that does not support directory sync.
+
+Sync calls request persistence from the operating system; they cannot guarantee
+the behavior of every filesystem, storage device, or hardware buffer. A failure
+before `os.replace` leaves an existing destination unchanged. If directory
+sync fails after replacement, `DurabilityError` is raised: the new destination
+is already visible, but its persistence is uncertain. If replacement itself fails,
+the operating system error is propagated. Abrupt process termination can leave a
+temporary file behind; ordinary exception cleanup is best effort. A crash with
+`"none"` can leave the new file empty or truncated even after the rename, so
+the runtime visibility guarantee is not a crash-recovery guarantee. On macOS,
+`os.fsync` does not request the stronger `F_FULLFSYNC` operation, so even a
+successful sync does not guarantee that hardware buffers reached durable media.
+
+## License
+
+BSD 3-Clause License. See the repository's LICENSE.

kitsuyui_fileio-0.8.1/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "kitsuyui.fileio"
+dynamic = ["version"]
+description = "Explicit and safe file writing utilities"
+license = "BSD-3-Clause"
+requires-python = ">=3.10"
+readme = { file = "README.md", content-type = "text/markdown" }
+authors = [{name = "Yui KITSU", email = "kitsuyui+github@kitsuyui.com"}]
+classifiers = ["Development Status :: 3 - Alpha"]
+
+[project.urls]
+Homepage = "https://github.com/kitsuyui/pypi-playground"
+
+[build-system]
+requires = ["setuptools>=77", "setuptools_scm"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+package-data = { "*" = ["py.typed"] }
+
+[tool.setuptools.packages.find]
+where = ["src/"]
+include = ["kitsuyui.fileio"]
+
+[tool.setuptools_scm]
+version_file = "./src/kitsuyui/fileio/_version.py"
+root = "../.."
+
+[dependency-groups]
+dev = ["dev-shared"]
+
+[tool.uv.sources]
+dev-shared = { workspace = true }
+
+[tool.poe]
+include = "../../dev-shared/poe.tasks.toml"

kitsuyui_fileio-0.8.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kitsuyui_fileio-0.8.1/src/kitsuyui/fileio/__init__.py

@@ -0,0 +1,17 @@
+"""File I/O primitives with explicit replacement and durability semantics."""
+
+from ._atomic import (
+    Durability,
+    DurabilityError,
+    atomic_write,
+    atomic_write_bytes,
+    atomic_write_text,
+)
+
+__all__ = [
+    "Durability",
+    "DurabilityError",
+    "atomic_write",
+    "atomic_write_bytes",
+    "atomic_write_text",
+]

kitsuyui_fileio-0.8.1/src/kitsuyui/fileio/_atomic.py

@@ -0,0 +1,209 @@
+"""Atomically replace a single file with staged bytes."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import tempfile
+from collections.abc import Generator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import BinaryIO, Literal
+
+Durability = Literal["none", "file", "file_and_directory"]
+
+
+class DurabilityError(OSError):
+    """The replacement happened, but the directory could not be synced."""
+
+
+def _validate_options(durability: Durability) -> None:
+    if durability not in ("none", "file", "file_and_directory"):
+        raise ValueError(f"invalid durability: {durability!r}")
+    if durability == "file_and_directory" and os.name != "posix":
+        raise NotImplementedError("directory sync is only supported on POSIX")
+
+
+def _validate_permissions(permissions: int | None) -> None:
+    if permissions is not None and not 0 <= permissions <= 0o777:
+        raise ValueError("permissions must be between 0 and 0o777")
+
+
+def _destination(path: str | os.PathLike[str]) -> Path:
+    given_path = Path(path)
+    if given_path.name in ("", ".", ".."):
+        raise ValueError("path must name a file")
+    # Resolve the parent only: the destination symlink must be replaced.
+    return given_path.parent.resolve() / given_path.name
+
+
+@contextlib.contextmanager
+def _directory_handle(
+    destination: Path, durability: Durability
+) -> Generator[int | None, None, None]:
+    fd = None
+    try:
+        if durability == "file_and_directory":
+            fd = os.open(
+                destination.parent, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+            )
+        yield fd
+    finally:
+        if fd is not None:
+            with contextlib.suppress(OSError):
+                os.close(fd)
+
+
+@dataclass
+class _StagedPath:
+    path: Path
+    owned: bool = True
+
+    def replace(self, destination: Path) -> None:
+        self.path.replace(destination)
+        self.owned = False
+
+    def cleanup(self) -> None:
+        if self.owned:
+            with contextlib.suppress(OSError):
+                self.path.unlink()
+
+
+@contextlib.contextmanager
+def _staged_file(
+    destination: Path,
+) -> Generator[tuple[_StagedPath, BinaryIO], None, None]:
+    fd, name = tempfile.mkstemp(
+        prefix=".fileio-", suffix=".tmp", dir=destination.parent
+    )
+    temporary = _StagedPath(Path(name))
+    try:
+        with _owned_stream(fd) as stream:
+            yield temporary, stream
+    finally:
+        temporary.cleanup()
+
+
+@contextlib.contextmanager
+def _owned_stream(fd: int) -> Generator[BinaryIO, None, None]:
+    stream = _open_stream(fd)
+    try:
+        yield stream
+    except BaseException:
+        with contextlib.suppress(BaseException):
+            stream.close()
+        raise
+    else:
+        _close_stream(stream)
+
+
+def _close_stream(stream: BinaryIO) -> None:
+    if not stream.closed:
+        stream.close()
+
+
+def _open_stream(fd: int) -> BinaryIO:
+    try:
+        return os.fdopen(fd, "wb")
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.close(fd)
+        raise
+
+
+def _prepare_stream(
+    stream: BinaryIO,
+    temporary: Path,
+    durability: Durability,
+    permissions: int | None,
+) -> None:
+    _flush_stream(stream)
+    if permissions is not None:
+        _set_permissions(stream, temporary, permissions)
+    if durability != "none":
+        os.fsync(stream.fileno())
+
+
+def _flush_stream(stream: BinaryIO) -> None:
+    if stream.closed:
+        raise ValueError("the atomic_write stream was closed by the caller")
+    stream.flush()
+
+
+def _set_permissions(
+    stream: BinaryIO, temporary: Path, permissions: int
+) -> None:
+    if hasattr(os, "fchmod"):
+        os.fchmod(stream.fileno(), permissions)
+    else:
+        temporary.chmod(permissions)
+
+
+def _commit(
+    temporary: _StagedPath, destination: Path, directory_fd: int | None
+) -> None:
+    temporary.replace(destination)
+    if directory_fd is not None:
+        try:
+            os.fsync(directory_fd)
+        except OSError as exc:
+            raise DurabilityError(
+                f"file was replaced, but directory sync failed: {destination}"
+            ) from exc
+
+
+@contextlib.contextmanager
+def atomic_write(
+    path: str | os.PathLike[str],
+    *,
+    durability: Durability = "file",
+    permissions: int | None = None,
+) -> Generator[BinaryIO, None, None]:
+    """Yield a binary stream and replace the destination on successful exit.
+
+    The destination directory must exist. Temporary files are private (0600 on
+    POSIX); replacement does not preserve the original file's metadata.
+    """
+    _validate_options(durability)
+    _validate_permissions(permissions)
+    destination = _destination(path)
+    with (
+        _directory_handle(destination, durability) as directory_fd,
+        _staged_file(destination) as (temporary, stream),
+    ):
+        yield stream
+        _prepare_stream(stream, temporary.path, durability, permissions)
+        stream.close()
+        _commit(temporary, destination, directory_fd)
+
+
+def atomic_write_bytes(
+    path: str | os.PathLike[str],
+    data: bytes,
+    *,
+    durability: Durability = "file",
+    permissions: int | None = None,
+) -> None:
+    """Replace a file with bytes after the entire write succeeds."""
+    with atomic_write(
+        path, durability=durability, permissions=permissions
+    ) as stream:
+        stream.write(data)
+
+
+def atomic_write_text(
+    path: str | os.PathLike[str],
+    text: str,
+    *,
+    encoding: str = "utf-8",
+    errors: str = "strict",
+    durability: Durability = "file",
+    permissions: int | None = None,
+) -> None:
+    """Encode text and replace a file after the entire write succeeds."""
+    atomic_write_bytes(
+        path,
+        text.encode(encoding, errors),
+        durability=durability,
+        permissions=permissions,
+    )

kitsuyui_fileio-0.8.1/src/kitsuyui/fileio/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.8.1'
+__version_tuple__ = version_tuple = (0, 8, 1)
+
+__commit_id__ = commit_id = 'g7c51344f1'

kitsuyui_fileio-0.8.1/src/kitsuyui.fileio.egg-info/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: kitsuyui.fileio
+Version: 0.8.1
+Summary: Explicit and safe file writing utilities
+Author-email: Yui KITSU <kitsuyui+github@kitsuyui.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/kitsuyui/pypi-playground
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# kitsuyui.fileio
+
+Small, explicit file I/O primitives. The first release provides atomic
+replacement of a single file without runtime dependencies (Python 3.10+).
+
+```python
+from kitsuyui.fileio import atomic_write, atomic_write_bytes, atomic_write_text
+
+atomic_write_text("settings.txt", "ready\n")
+atomic_write_bytes("data.bin", b"\x00\x01")
+with atomic_write("large.bin") as output:
+    output.write(b"first chunk")
+    output.write(b"second chunk")
+```
+
+`atomic_write` yields a binary stream. On normal exit it flushes and closes the
+stream before replacing the destination. An exception inside the block leaves
+the destination untouched and removes the temporary file when possible. Do not
+close the yielded stream manually. The convenience functions accept paths and
+bytes or text respectively; text is encoded as UTF-8 unless specified otherwise.
+The parent directory must already exist. A caller that wraps the binary stream
+in a `TextIOWrapper` must flush and detach the wrapper before leaving the block;
+closing the supplied stream causes a `ValueError` and cancels replacement.
+Text convenience writes use `str.encode` and do not translate newlines; callers
+may choose the encoding and encoding error handler.
+
+## Guarantees and boundaries
+
+The temporary file is created in the destination directory and installed with
+`os.replace`. On a filesystem supporting POSIX atomic rename, a reader opening
+the destination sees either the previous file or the complete new file during
+normal execution; an
+already-open descriptor may continue to refer to the old file. On other systems
+and filesystems, replacement guarantees depend on the platform. This does not
+lock writers, prevent lost updates, make multiple replacements transactional, or
+secure a directory controlled by an untrusted party. Concurrent successful
+writers are last-replacement-wins. A destination symlink itself is replaced;
+its target is not modified. The temporary file is created with restrictive
+permissions (0600 on POSIX). Existing ownership, permissions, timestamps, ACLs,
+extended attributes and hard links are not preserved. The restrictive default
+avoids silently exposing content from a private file or temporary write. To
+choose another POSIX permission mode, pass `permissions=0o644` (for example);
+the specified bits are applied to the temporary file before replacement and
+are not filtered by umask. Do not use permissive modes for sensitive data. On
+Windows `os.chmod` has limited permission semantics. Copying existing permissions
+is deliberately left to the caller because metadata and access policy are
+platform-specific and can change concurrently.
+
+The keyword `durability` distinguishes visibility from persistence:
+
+* `"none"`: flush and close before replacement; no `fsync`.
+* `"file"` (default): also `fsync` the staged file before replacement.
+* `"file_and_directory"`: also `fsync` the parent directory after replacement.
+  This option is available only on POSIX and can still fail on a filesystem
+  that does not support directory sync.
+
+Sync calls request persistence from the operating system; they cannot guarantee
+the behavior of every filesystem, storage device, or hardware buffer. A failure
+before `os.replace` leaves an existing destination unchanged. If directory
+sync fails after replacement, `DurabilityError` is raised: the new destination
+is already visible, but its persistence is uncertain. If replacement itself fails,
+the operating system error is propagated. Abrupt process termination can leave a
+temporary file behind; ordinary exception cleanup is best effort. A crash with
+`"none"` can leave the new file empty or truncated even after the rename, so
+the runtime visibility guarantee is not a crash-recovery guarantee. On macOS,
+`os.fsync` does not request the stronger `F_FULLFSYNC` operation, so even a
+successful sync does not guarantee that hardware buffers reached durable media.
+
+## License
+
+BSD 3-Clause License. See the repository's LICENSE.

kitsuyui_fileio-0.8.1/src/kitsuyui.fileio.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/kitsuyui.fileio.egg-info/PKG-INFO
+src/kitsuyui.fileio.egg-info/SOURCES.txt
+src/kitsuyui.fileio.egg-info/dependency_links.txt
+src/kitsuyui.fileio.egg-info/scm_file_list.json
+src/kitsuyui.fileio.egg-info/scm_version.json
+src/kitsuyui.fileio.egg-info/top_level.txt
+src/kitsuyui/fileio/__init__.py
+src/kitsuyui/fileio/_atomic.py
+src/kitsuyui/fileio/_version.py
+src/kitsuyui/fileio/py.typed
+tests/test_atomic.py

kitsuyui_fileio-0.8.1/src/kitsuyui.fileio.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kitsuyui_fileio-0.8.1/src/kitsuyui.fileio.egg-info/scm_file_list.json

@@ -0,0 +1,11 @@
+{
+  "files": [
+    "LICENSE",
+    "README.md",
+    "pyproject.toml",
+    "src/kitsuyui/fileio/__init__.py",
+    "src/kitsuyui/fileio/_atomic.py",
+    "src/kitsuyui/fileio/py.typed",
+    "tests/test_atomic.py"
+  ]
+}

kitsuyui_fileio-0.8.1/src/kitsuyui.fileio.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.8.1",
+  "distance": 0,
+  "node": "g7c51344f11f58cd518e66a0e3af0c60a0abc403b",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-27"
+}

kitsuyui_fileio-0.8.1/src/kitsuyui.fileio.egg-info/top_level.txt

@@ -0,0 +1 @@
+kitsuyui

kitsuyui_fileio-0.8.1/tests/test_atomic.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import os
+import threading
+from collections.abc import Generator
+from pathlib import Path
+from typing import Any, cast
+from unittest.mock import patch
+
+import pytest
+
+from kitsuyui.fileio import (
+    DurabilityError,
+    atomic_write,
+    atomic_write_bytes,
+    atomic_write_text,
+)
+
+
+def test_text_and_bytes_replace_existing_file(tmp_path: Path) -> None:
+    path = tmp_path / "data"
+    path.write_bytes(b"old")
+    atomic_write_text(path, "na\u00efve", encoding="utf-8")
+    assert path.read_bytes() == "na\u00efve".encode()
+    atomic_write_bytes(path, b"new")
+    assert path.read_bytes() == b"new"
+    assert list(tmp_path.iterdir()) == [path]
+
+
+def test_context_error_preserves_original_and_removes_temporary(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "data"
+    path.write_bytes(b"old")
+    with pytest.raises(ValueError, match="stop"), atomic_write(path) as stream:
+        stream.write(b"partial")
+        raise ValueError("stop")
+    assert path.read_bytes() == b"old"
+    assert list(tmp_path.iterdir()) == [path]
+
+
+@pytest.mark.parametrize(
+    ("target", "operation"), [(Path, "replace"), (os, "fsync")]
+)
+def test_precommit_failure_keeps_original(
+    tmp_path: Path, target: Any, operation: str
+) -> None:
+    path = tmp_path / "data"
+    path.write_bytes(b"old")
+    with (
+        patch.object(target, operation, side_effect=OSError("injected")),
+        pytest.raises(OSError, match="injected"),
+    ):
+        atomic_write_bytes(path, b"new")
+    assert path.read_bytes() == b"old"
+    assert list(tmp_path.iterdir()) == [path]
+
+
+@pytest.mark.skipif(os.name != "posix", reason="directory fsync is POSIX-only")
+def test_directory_sync_failure_reports_visible_replacement(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "data"
+    path.write_bytes(b"old")
+    original_fsync = os.fsync
+    calls = 0
+
+    def fail_second(fd: int) -> None:
+        nonlocal calls
+        calls += 1
+        if calls == 2:
+            raise OSError("directory sync failed")
+        original_fsync(fd)
+
+    with (
+        patch.object(os, "fsync", side_effect=fail_second),
+        pytest.raises(DurabilityError),
+    ):
+        atomic_write_bytes(path, b"new", durability="file_and_directory")
+    assert path.read_bytes() == b"new"
+    assert list(tmp_path.iterdir()) == [path]
+
+
+def _write_versions(path: Path, versions: tuple[bytes, bytes]) -> None:
+    for index in range(30):
+        atomic_write_bytes(path, versions[index % 2], durability="none")
+
+
+@pytest.mark.skipif(
+    os.name == "nt", reason="Windows may deny replacement of an open file"
+)
+def test_reader_sees_only_complete_versions(tmp_path: Path) -> None:
+    path = tmp_path / "data"
+    versions = (b"a" * 32768, b"b" * 32768)
+    path.write_bytes(versions[0])
+    observed: list[bytes] = []
+    done = threading.Event()
+
+    def reader() -> None:
+        while not done.is_set():
+            observed.append(path.read_bytes())
+
+    thread = threading.Thread(target=reader)
+    thread.start()
+    try:
+        _write_versions(path, versions)
+    finally:
+        done.set()
+        thread.join()
+    assert observed
+    assert all(value in versions for value in observed)
+
+
+@pytest.mark.skipif(os.name != "posix", reason="POSIX permission semantics")
+def test_permissions_and_symlink_replacement(tmp_path: Path) -> None:
+    target = tmp_path / "target"
+    target.write_bytes(b"unchanged")
+    path = tmp_path / "link"
+    path.symlink_to(target)
+    atomic_write_bytes(path, b"new")
+    assert not path.is_symlink()
+    assert target.read_bytes() == b"unchanged"
+    assert path.stat().st_mode & 0o777 == 0o600
+
+
+def test_invalid_durability_does_not_create_files(tmp_path: Path) -> None:
+    with pytest.raises(ValueError):
+        atomic_write_bytes(
+            tmp_path / "data", b"new", durability=cast(Any, "unknown")
+        )
+    assert list(tmp_path.iterdir()) == []
+
+
+def test_body_exception_survives_close_failure(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    path = tmp_path / "data"
+    path.write_bytes(b"old")
+    with (
+        pytest.raises(RuntimeError, match="body"),
+        atomic_write(path) as stream,
+    ):
+        real_close = stream.close
+
+        def fail_close() -> None:
+            real_close()
+            raise OSError("close")
+
+        monkeypatch.setattr(stream, "close", fail_close)
+        raise RuntimeError("body")
+    assert path.read_bytes() == b"old"
+
+
+def test_caller_close_has_clear_error_and_preserves_old(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "data"
+    path.write_bytes(b"old")
+    with (
+        pytest.raises(ValueError, match="closed by the caller"),
+        atomic_write(path) as stream,
+    ):
+        stream.write(b"new")
+        stream.close()
+    assert path.read_bytes() == b"old"
+    assert list(tmp_path.iterdir()) == [path]
+
+
+@pytest.mark.skipif(os.name != "posix", reason="POSIX permission semantics")
+def test_explicit_permissions(tmp_path: Path) -> None:
+    path = tmp_path / "data"
+    atomic_write_text(path, "hi", permissions=0o640)
+    assert path.stat().st_mode & 0o777 == 0o640
+
+
+@pytest.mark.skipif(os.name != "posix", reason="symlink availability")
+def test_parent_symlink_dotdot_resolves_like_os(tmp_path: Path) -> None:
+    nested = tmp_path / "other" / "nested"
+    nested.mkdir(parents=True)
+    (tmp_path / "link").symlink_to(nested, target_is_directory=True)
+    atomic_write_bytes(tmp_path / "link" / ".." / "data", b"yes")
+    assert (tmp_path / "other" / "data").read_bytes() == b"yes"
+    assert not (tmp_path / "data").exists()
+
+
+def test_long_destination_and_encoding_errors(tmp_path: Path) -> None:
+    path = tmp_path / ("x" * 240)
+    atomic_write_text(path, "na\u00efve", encoding="ascii", errors="replace")
+    assert path.read_bytes() == b"na?ve"
+
+
+def test_invalid_permissions_does_not_create_file(tmp_path: Path) -> None:
+    with pytest.raises(ValueError, match="permissions"):
+        atomic_write_bytes(tmp_path / "data", b"new", permissions=0o1000)
+    assert list(tmp_path.iterdir()) == []
+
+
+@pytest.fixture
+def reused_temporary_name() -> Generator[list[Path], None, None]:
+    recreated: list[Path] = []
+    real_replace = Path.replace
+
+    def replace_and_recreate(source: Path, destination: Path) -> Path:
+        result = real_replace(source, destination)
+        source.write_bytes(b"another writer")
+        recreated.append(source)
+        return result
+
+    with patch.object(Path, "replace", replace_and_recreate):
+        yield recreated
+
+
+def test_reused_temporary_name_survives_success(
+    tmp_path: Path, reused_temporary_name: list[Path]
+) -> None:
+    path = tmp_path / "data"
+    atomic_write_bytes(path, b"new")
+    assert path.read_bytes() == b"new"
+    assert len(reused_temporary_name) == 1
+    assert reused_temporary_name[0].read_bytes() == b"another writer"
+
+
+@pytest.mark.skipif(os.name != "posix", reason="directory fsync is POSIX-only")
+def test_reused_temporary_name_survives_directory_sync_failure(
+    tmp_path: Path, reused_temporary_name: list[Path]
+) -> None:
+    path = tmp_path / "data"
+    with (
+        patch.object(os, "fsync", side_effect=[None, OSError("sync failed")]),
+        pytest.raises(DurabilityError),
+    ):
+        atomic_write_bytes(path, b"new", durability="file_and_directory")
+    assert path.read_bytes() == b"new"
+    assert len(reused_temporary_name) == 1
+    assert reused_temporary_name[0].read_bytes() == b"another writer"