durablewrite 0.2.0__py3-none-any.whl

durablewrite/__init__.py

@@ -0,0 +1,26 @@
+"""Durable, cross-platform atomic file writes (temp-same-dir, os.replace, fsync)."""
+
+from __future__ import annotations
+
+from ._atomic import atomic_write
+from ._cleanup import cleanup_temp_files
+from ._errors import DirectorySyncError, DurableWriteError, SharingViolationError
+from ._helpers import write_bytes_atomic, write_json_atomic, write_text_atomic
+from ._options import DEFAULT_RETRY, NO_RETRY, FsyncLevel, RetryPolicy
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "DEFAULT_RETRY",
+    "NO_RETRY",
+    "DirectorySyncError",
+    "DurableWriteError",
+    "FsyncLevel",
+    "RetryPolicy",
+    "SharingViolationError",
+    "atomic_write",
+    "cleanup_temp_files",
+    "write_bytes_atomic",
+    "write_json_atomic",
+    "write_text_atomic",
+]

durablewrite/__main__.py

@@ -0,0 +1,9 @@
+"""Allow ``python -m durablewrite``."""
+
+from __future__ import annotations
+
+import sys
+
+from ._cli import main
+
+sys.exit(main())

durablewrite/_atomic.py

@@ -0,0 +1,141 @@
+"""The atomic write context manager: temp file, flush, fsync, rename, fsync dir."""
+
+from __future__ import annotations
+
+import errno
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import IO, Any
+
+from ._errors import DirectorySyncError
+from ._fs import (
+    StrPath,
+    apply_metadata,
+    create_temp,
+    existing_stat,
+    fsync_directory,
+    resolve_target,
+)
+from ._options import DEFAULT_RETRY, FsyncLevel, RetryPolicy, resolve_fsync
+from ._replace import publish, remove_temp
+
+_VALID_MODES = ("w", "wb")
+
+
+def _check_mode(mode: str, encoding: str | None, newline: str | None) -> bool:
+    if mode not in _VALID_MODES:
+        raise ValueError(f"mode must be one of {_VALID_MODES!r}, got {mode!r}")
+    binary = mode == "wb"
+    if binary and encoding is not None:
+        raise ValueError("encoding is not allowed in binary mode")
+    if binary and newline is not None:
+        raise ValueError("newline is not allowed in binary mode")
+    return binary
+
+
+@contextmanager
+def atomic_write(
+    path: StrPath,
+    mode: str = "w",
+    *,
+    encoding: str | None = None,
+    newline: str | None = None,
+    durable: bool = True,
+    fsync_dir: bool = True,
+    fsync: FsyncLevel | None = None,
+    overwrite: bool = True,
+    preserve_mode: bool = True,
+    permissions: int | None = None,
+    preserve_owner: bool = False,
+    follow_symlinks: bool = True,
+    retry: RetryPolicy = DEFAULT_RETRY,
+) -> Iterator[IO[Any]]:
+    """Write to ``path`` so readers only ever see the old file or the complete new one.
+
+    The block writes to a temp file created in the target's own directory (so
+    the final rename never crosses a filesystem). When the block exits normally
+    the data is flushed, fsynced according to ``fsync``, and moved onto ``path``
+    with ``os.replace``. If the block raises, ``path`` is untouched and the temp
+    file is removed. Closing the handle inside the block is an error: the write
+    is discarded and :class:`ValueError` is raised. While it is written, the
+    temp file is only readable by its owner whenever the final mode comes from
+    ``permissions`` or from the replaced file.
+
+    Args:
+        path: The file to create or replace.
+        mode: ``"w"`` for text (UTF-8 unless ``encoding`` is given) or ``"wb"``.
+        encoding: Text encoding; not allowed in binary mode.
+        newline: Passed to the text wrapper as in :func:`open`.
+        durable: Legacy flag for the file fsync; ignored when ``fsync`` is given.
+        fsync_dir: Legacy flag for the directory fsync; ignored when ``fsync`` is given.
+        fsync: ``"none"``, ``"file"`` or ``"full"`` (see :data:`FsyncLevel`).
+            Defaults to the legacy flags, which mean ``"full"``.
+        overwrite: When False, publish only if nothing exists at ``path`` and
+            raise :class:`FileExistsError` otherwise, atomically.
+        preserve_mode: Copy the permission bits of an existing target (POSIX).
+            New files get ``0o666`` minus the umask, as with :func:`open`.
+        permissions: Explicit permission bits; wins over ``preserve_mode``.
+            On Windows only the read-only flag is affected.
+        preserve_owner: Copy uid and gid of an existing target (POSIX only;
+            usually needs privileges to change the uid). Ignored on Windows.
+        follow_symlinks: When ``path`` is a symlink, replace the file it points
+            to and keep the link (default), or replace the link itself.
+        retry: How long to retry a rename blocked by a Windows lock.
+
+    Raises:
+        ValueError: An invalid ``mode``, ``fsync`` or argument combination, or
+            a ``path`` that is empty or ends with a path separator.
+        IsADirectoryError: ``path`` is an existing directory (or, when
+            following symlinks, a link to one).
+        FileExistsError: ``overwrite`` is False and ``path`` exists.
+        SharingViolationError: The rename stayed blocked for the whole retry budget.
+        DirectorySyncError: The file was replaced, but the directory fsync failed.
+    """
+    binary = _check_mode(mode, encoding, newline)
+    sync_file, sync_dir = resolve_fsync(fsync, durable, fsync_dir)
+    target = resolve_target(os.fspath(path), follow_symlinks)
+    if os.path.isdir(target) and not os.path.islink(target):
+        raise IsADirectoryError(errno.EISDIR, "target is a directory", target)
+    if not overwrite and os.path.lexists(target):
+        raise FileExistsError(errno.EEXIST, "target already exists", target)
+    directory = os.path.dirname(os.path.abspath(target))
+    existing = existing_stat(target, follow_symlinks)
+    private = permissions is not None or (preserve_mode and existing is not None)
+    tmp: str | None = None
+    published = False
+    try:
+        fd, tmp = create_temp(directory, os.path.basename(target), private)
+        try:
+            if binary:
+                handle: IO[Any] = os.fdopen(fd, "wb")
+            else:
+                handle = os.fdopen(fd, "w", encoding=encoding or "utf-8", newline=newline)
+        except BaseException:
+            os.close(fd)
+            raise
+        with handle as f:
+            yield f
+            f.flush()
+            apply_metadata(
+                f.fileno(),
+                tmp,
+                existing,
+                preserve_mode=preserve_mode,
+                permissions=permissions,
+                preserve_owner=preserve_owner,
+            )
+            if sync_file:
+                os.fsync(f.fileno())
+        publish(tmp, target, overwrite=overwrite, retry=retry)
+        published = True
+    finally:
+        if tmp is not None and not published:
+            remove_temp(tmp, retry)
+    if sync_dir:
+        try:
+            fsync_directory(directory)
+        except OSError as exc:
+            raise DirectorySyncError(
+                exc.errno, f"file replaced, but its directory was not synced: {exc}", directory
+            ) from exc

durablewrite/_cleanup.py

@@ -0,0 +1,63 @@
+"""Removal of temp files left behind by writers that were killed mid-write."""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+
+from ._fs import TEMP_SUFFIX, StrPath, temp_stem
+
+_TAIL = r"\.[0-9a-f]{8}" + re.escape(TEMP_SUFFIX) + r"$"
+_TEMP_NAME = re.compile(r"^\..+" + _TAIL, re.DOTALL)
+
+
+def cleanup_temp_files(
+    directory: StrPath,
+    *,
+    older_than: float = 3600.0,
+    target: StrPath | None = None,
+    now: float | None = None,
+) -> list[str]:
+    """Delete stale durablewrite temp files in ``directory`` and return their paths.
+
+    A writer that is killed (or loses power) between creating its temp file and
+    renaming it cannot clean up after itself. Such files are named
+    ``.<target name>.<8 hex digits>.dwtmp``; only regular files matching that
+    pattern are considered, so nothing else in the directory is ever touched.
+
+    Args:
+        directory: The directory to scan (not recursive).
+        older_than: Minimum age in seconds, by modification time. The default of
+            one hour leaves alone the temp files of running writers, unless a
+            writer keeps one open for longer than that; pass ``0`` only when
+            you know no writer is active.
+        target: Restrict the cleanup to temp files of this one target file.
+        now: The current time as a Unix timestamp; defaults to :func:`time.time`.
+
+    Returns:
+        The removed paths, sorted. Files that vanish concurrently or that are
+        still held open (Windows refuses to delete them) are skipped.
+    """
+    if older_than < 0:
+        raise ValueError("older_than must not be negative")
+    cutoff = (time.time() if now is None else now) - older_than
+    pattern = _TEMP_NAME
+    if target is not None:
+        stem = temp_stem(os.path.basename(os.fspath(target)))
+        pattern = re.compile(r"^\." + re.escape(stem) + _TAIL, re.DOTALL)
+    removed: list[str] = []
+    with os.scandir(directory) as entries:
+        for entry in entries:
+            if not pattern.match(entry.name):
+                continue
+            try:
+                if not entry.is_file(follow_symlinks=False):
+                    continue
+                if entry.stat(follow_symlinks=False).st_mtime > cutoff:
+                    continue
+                os.remove(entry.path)
+            except (FileNotFoundError, PermissionError):
+                continue
+            removed.append(entry.path)
+    return sorted(removed)

durablewrite/_cli.py

@@ -0,0 +1,178 @@
+"""``durablewrite`` command: write standard input to a file atomically, like sponge."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import stat
+import sys
+from typing import IO, NoReturn
+
+from . import __version__
+from ._atomic import atomic_write
+from ._errors import DirectorySyncError
+from ._options import RetryPolicy
+
+_EPILOG = """\
+examples:
+  sort names.txt | durablewrite names.txt
+      sort a file in place; names.txt is replaced only after sort finishes
+  jq '.debug = true' config.json | durablewrite --json config.json
+      edit JSON in place; invalid output never replaces the file
+  echo "one more line" | durablewrite --append notes.txt
+      append atomically: readers see the old file or the longer one
+  printf 's3cret' | durablewrite --permissions 600 --no-overwrite token.txt
+      create a private file, failing if it already exists
+
+The target is replaced only once standard input reaches end of file, so a
+pipeline may read the same file it writes (sort f | durablewrite f). On POSIX
+`durablewrite f < f` works too; on Windows the shell keeps a redirected file
+open, which blocks the rename, so that form is refused: pipe the file instead.
+Concurrent --append runs may lose each other's lines.
+
+exit status: 0 on success; 1 on any error, with the target left as it was;
+3 when the target was replaced but its directory could not be fsynced.
+"""
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        self.exit(1, f"{self.prog}: error: {message}\n")
+
+
+def _octal(text: str) -> int:
+    try:
+        value = int(text, 8)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"not an octal mode: {text!r}") from None
+    if not 0 <= value <= 0o7777:
+        raise argparse.ArgumentTypeError(f"mode out of range: {text!r}")
+    return value
+
+
+def _positive(text: str) -> int:
+    try:
+        value = int(text)
+    except ValueError:
+        value = 0
+    if value < 1:
+        raise argparse.ArgumentTypeError(f"must be a positive integer: {text!r}")
+    return value
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Return the argument parser for the ``durablewrite`` command."""
+    parser = _Parser(
+        prog="durablewrite",
+        description="Read standard input and write it to TARGET atomically and durably.",
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("target", metavar="TARGET", help="file to create or replace")
+    parser.add_argument("--version", action="version", version=f"durablewrite {__version__}")
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument(
+        "-a", "--append", action="store_true", help="keep the current content and add stdin"
+    )
+    mode.add_argument(
+        "--json", action="store_true", help="refuse to write unless stdin is valid UTF-8 JSON"
+    )
+    parser.add_argument(
+        "--fsync",
+        choices=("none", "file", "full"),
+        default="full",
+        help="what to flush to disk before returning (default: full)",
+    )
+    parser.add_argument("--no-overwrite", action="store_true", help="fail if TARGET already exists")
+    parser.add_argument(
+        "--permissions", type=_octal, metavar="OCTAL", help="permission bits, e.g. 644"
+    )
+    parser.add_argument(
+        "--no-follow-symlinks",
+        action="store_true",
+        help="replace a symlink TARGET itself instead of the file it points to",
+    )
+    parser.add_argument(
+        "--attempts",
+        type=_positive,
+        default=8,
+        metavar="N",
+        help="rename attempts while Windows reports TARGET locked (default: 8)",
+    )
+    return parser
+
+
+def _reject_constant(name: str) -> None:
+    raise ValueError(f"{name} is not valid JSON")
+
+
+def _check_json(payload: bytes) -> None:
+    try:
+        json.loads(payload.decode("utf-8"), parse_constant=_reject_constant)
+    except (ValueError, RecursionError) as exc:
+        raise ValueError(f"standard input is not valid UTF-8 JSON ({exc})") from exc
+
+
+def _refuse_redirected_target(source: IO[bytes], target: str) -> None:
+    """On Windows, fail fast when standard input is the target file itself."""
+    if os.name != "nt":
+        return
+    try:
+        src, dst = os.fstat(source.fileno()), os.stat(target)
+    except (OSError, ValueError):
+        return
+    if stat.S_ISREG(src.st_mode) and os.path.samestat(src, dst):
+        raise ValueError(
+            "on Windows TARGET cannot also be redirected into standard input: the shell "
+            "keeps it open, which blocks the rename. Pipe it instead: type FILE | durablewrite FILE"
+        )
+
+
+def _write(args: argparse.Namespace, source: IO[bytes]) -> None:
+    _refuse_redirected_target(source, args.target)
+    payload: bytes | None = None
+    if args.json:
+        payload = source.read()
+        _check_json(payload)
+    with atomic_write(
+        args.target,
+        "wb",
+        fsync=args.fsync,
+        overwrite=not args.no_overwrite,
+        permissions=args.permissions,
+        follow_symlinks=not args.no_follow_symlinks,
+        retry=RetryPolicy(max_attempts=args.attempts),
+    ) as out:
+        if args.append:
+            try:
+                with open(args.target, "rb") as current:
+                    shutil.copyfileobj(current, out)
+            except FileNotFoundError:
+                pass
+        if payload is not None:
+            out.write(payload)
+        else:
+            shutil.copyfileobj(source, out)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the command line tool and return its exit status."""
+    args = build_parser().parse_args(argv)
+    if sys.stdin is None:
+        print("durablewrite: error: standard input is closed", file=sys.stderr)
+        return 1
+    try:
+        _write(args, sys.stdin.buffer)
+    except DirectorySyncError as exc:
+        print(f"durablewrite: warning: {args.target}: {exc}", file=sys.stderr)
+        return 3
+    except (OSError, ValueError) as exc:
+        print(f"durablewrite: error: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("durablewrite: interrupted, target left unchanged", file=sys.stderr)
+        return 130
+    return 0

durablewrite/_errors.py

@@ -0,0 +1,40 @@
+"""Exceptions raised by durablewrite itself."""
+
+from __future__ import annotations
+
+
+class DurableWriteError(OSError):
+    """Base class for errors that durablewrite raises on its own.
+
+    It subclasses :class:`OSError`, so code that already handles ``OSError``
+    around a file write keeps working unchanged.
+    """
+
+
+class SharingViolationError(DurableWriteError, PermissionError):
+    """The target stayed locked by another process for the whole retry budget.
+
+    Raised on Windows when ``MoveFileExW`` keeps failing with
+    ``ERROR_ACCESS_DENIED``, ``ERROR_SHARING_VIOLATION`` or
+    ``ERROR_LOCK_VIOLATION`` because something holds the target (or the fresh
+    temp file) open without ``FILE_SHARE_DELETE``: another process, an antivirus
+    scanner or the search indexer. A directory ACL that denies the rename looks
+    the same to Windows and ends here too. The original target is untouched.
+    The temp file is removed, retrying under the same policy while it is locked;
+    if it stays locked it is left for :func:`~durablewrite.cleanup_temp_files`.
+    ``attempts`` is the number of rename attempts made. The last underlying
+    error, with its ``winerror`` code, is chained as ``__cause__``.
+    """
+
+    attempts: int = 0
+
+
+class DirectorySyncError(DurableWriteError):
+    """The file was replaced, but its directory could not be fsynced afterwards.
+
+    The new content is in place and readers see it, but the rename may not
+    survive a power loss. Raised only with ``fsync="full"`` on POSIX, for
+    example when the directory cannot be opened for reading or the filesystem
+    refuses to fsync directories. ``filename`` is the directory; the
+    underlying error is chained as ``__cause__``.
+    """

durablewrite/_fs.py

@@ -0,0 +1,134 @@
+"""Low-level filesystem steps: temp file creation, metadata, fsync, removal."""
+
+from __future__ import annotations
+
+import errno
+import hashlib
+import os
+import secrets
+import stat
+import sys
+from typing import Union
+
+StrPath = Union[str, "os.PathLike[str]"]
+
+TEMP_SUFFIX = ".dwtmp"
+# Keeps ".<stem>.<8 hex>.dwtmp" under the 255-byte name limit even for 4-byte UTF-8.
+_MAX_STEM_CHARS = 48
+_CREATE_FLAGS = (
+    os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0) | getattr(os, "O_CLOEXEC", 0)
+)
+
+
+def temp_stem(base: str) -> str:
+    """Return the part of a temp file name that identifies target ``base``.
+
+    Short names are used as is. Longer ones keep a readable head plus a hash of
+    the full name, so two long names never share temp files.
+    """
+    if len(base) <= _MAX_STEM_CHARS:
+        return base
+    digest = hashlib.sha256(base.encode("utf-8", "surrogatepass")).hexdigest()[:8]
+    return f"{base[: _MAX_STEM_CHARS - 9]}~{digest}"
+
+
+def resolve_target(path: str, follow_symlinks: bool) -> str:
+    """Return the path whose directory entry the rename will replace."""
+    if not path:
+        raise ValueError("path must not be empty")
+    if path.endswith(os.sep) or (os.altsep is not None and path.endswith(os.altsep)):
+        raise ValueError(f"path must name a file, not end with a separator: {path!r}")
+    if follow_symlinks and os.path.islink(path):
+        return os.path.realpath(path)
+    return path
+
+
+def existing_stat(path: str, follow_symlinks: bool) -> os.stat_result | None:
+    """Stat the file being replaced, or None for a new file.
+
+    A symlink that is itself replaced (``follow_symlinks=False``) counts as a
+    new file: the mode of whatever it points to is not inherited.
+    """
+    try:
+        if not follow_symlinks and os.path.islink(path):
+            return None
+        return os.stat(path)
+    except FileNotFoundError:
+        return None
+
+
+def create_temp(directory: str, base: str, private: bool) -> tuple[int, str]:
+    """Create an empty temp file next to the target and return ``(fd, path)``.
+
+    ``private`` creates it as ``0o600`` so content meant for a restrictive final
+    mode is never readable by others while it is written. Otherwise ``0o666``
+    lets the process umask apply exactly as it does for ``open()``.
+    """
+    prefix = f".{temp_stem(base)}."
+    mode = 0o600 if private else 0o666
+    for _ in range(100):
+        path = os.path.join(directory, f"{prefix}{secrets.token_hex(4)}{TEMP_SUFFIX}")
+        try:
+            return os.open(path, _CREATE_FLAGS, mode), path
+        except FileExistsError:
+            continue
+    raise FileExistsError(errno.EEXIST, "could not pick a free temp file name", directory)
+
+
+def apply_metadata(
+    fd: int,
+    tmp: str,
+    existing: os.stat_result | None,
+    *,
+    preserve_mode: bool,
+    permissions: int | None,
+    preserve_owner: bool,
+) -> None:
+    """Give the temp file the ownership and permission bits it should end with."""
+    if sys.platform != "win32" and preserve_owner and existing is not None:
+        # chown before chmod: chown clears setuid/setgid bits on Linux.
+        os.fchown(fd, existing.st_uid, existing.st_gid)
+    if permissions is not None:
+        os.chmod(tmp, permissions)
+    elif preserve_mode and existing is not None and os.name != "nt":
+        os.chmod(tmp, stat.S_IMODE(existing.st_mode))
+
+
+def fsync_directory(directory: str) -> None:
+    """Flush the directory entry so a completed rename survives power loss.
+
+    Windows offers no way to fsync a directory through the C runtime, so this
+    is a documented no-op there.
+    """
+    if os.name == "nt":
+        return
+    fd = os.open(directory, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def try_remove(path: str) -> bool | None:
+    """Remove ``path``: True if removed or gone, None if locked, False on other errors."""
+    try:
+        os.remove(path)
+        return True
+    except FileNotFoundError:
+        return True
+    except PermissionError as exc:
+        if os.name != "nt":
+            return False
+        if getattr(exc, "winerror", None) in (32, 33):
+            return None
+        try:
+            # A read-only attribute blocks deletion on Windows; clear it and retry once.
+            os.chmod(path, stat.S_IWRITE)
+            os.remove(path)
+            return True
+        except FileNotFoundError:
+            return True
+        except OSError:
+            return None
+    except OSError:
+        return False

durablewrite/_helpers.py

@@ -0,0 +1,132 @@
+"""One-shot helpers for text, bytes and JSON built on :func:`atomic_write`."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import Any
+
+from ._atomic import atomic_write
+from ._fs import StrPath
+from ._options import DEFAULT_RETRY, FsyncLevel, RetryPolicy
+
+
+def write_text_atomic(
+    path: StrPath,
+    text: str,
+    encoding: str = "utf-8",
+    *,
+    newline: str | None = None,
+    durable: bool = True,
+    fsync_dir: bool = True,
+    fsync: FsyncLevel | None = None,
+    overwrite: bool = True,
+    preserve_mode: bool = True,
+    permissions: int | None = None,
+    preserve_owner: bool = False,
+    follow_symlinks: bool = True,
+    retry: RetryPolicy = DEFAULT_RETRY,
+) -> None:
+    """Atomically replace ``path`` with ``text``.
+
+    Keyword arguments have the meaning documented on :func:`atomic_write`.
+    """
+    with atomic_write(
+        path,
+        "w",
+        encoding=encoding,
+        newline=newline,
+        durable=durable,
+        fsync_dir=fsync_dir,
+        fsync=fsync,
+        overwrite=overwrite,
+        preserve_mode=preserve_mode,
+        permissions=permissions,
+        preserve_owner=preserve_owner,
+        follow_symlinks=follow_symlinks,
+        retry=retry,
+    ) as f:
+        f.write(text)
+
+
+def write_bytes_atomic(
+    path: StrPath,
+    data: bytes,
+    *,
+    durable: bool = True,
+    fsync_dir: bool = True,
+    fsync: FsyncLevel | None = None,
+    overwrite: bool = True,
+    preserve_mode: bool = True,
+    permissions: int | None = None,
+    preserve_owner: bool = False,
+    follow_symlinks: bool = True,
+    retry: RetryPolicy = DEFAULT_RETRY,
+) -> None:
+    """Atomically replace ``path`` with ``data``.
+
+    Keyword arguments have the meaning documented on :func:`atomic_write`.
+    """
+    with atomic_write(
+        path,
+        "wb",
+        durable=durable,
+        fsync_dir=fsync_dir,
+        fsync=fsync,
+        overwrite=overwrite,
+        preserve_mode=preserve_mode,
+        permissions=permissions,
+        preserve_owner=preserve_owner,
+        follow_symlinks=follow_symlinks,
+        retry=retry,
+    ) as f:
+        f.write(data)
+
+
+def write_json_atomic(
+    path: StrPath,
+    obj: Any,
+    *,
+    indent: int | str | None = 2,
+    sort_keys: bool = False,
+    ensure_ascii: bool = False,
+    default: Callable[[Any], Any] | None = None,
+    allow_nan: bool = False,
+    fsync: FsyncLevel = "full",
+    overwrite: bool = True,
+    preserve_mode: bool = True,
+    permissions: int | None = None,
+    preserve_owner: bool = False,
+    follow_symlinks: bool = True,
+    retry: RetryPolicy = DEFAULT_RETRY,
+) -> None:
+    """Atomically replace ``path`` with ``obj`` encoded as UTF-8 JSON.
+
+    The value is serialised before any file is touched, so an object that
+    cannot be encoded raises :class:`TypeError` (or :class:`ValueError` for a
+    circular reference) and leaves both the target and the directory unchanged.
+    ``NaN`` and infinities are not valid JSON (RFC 8259), so they raise
+    :class:`ValueError` unless ``allow_nan=True``.
+    The output ends with a single ``\n`` and uses ``\n`` line endings on every
+    platform. ``indent``, ``sort_keys``, ``ensure_ascii``, ``default`` and ``allow_nan`` are
+    passed to :func:`json.dumps`; the rest is documented on :func:`atomic_write`.
+    """
+    text = json.dumps(
+        obj,
+        indent=indent,
+        sort_keys=sort_keys,
+        ensure_ascii=ensure_ascii,
+        default=default,
+        allow_nan=allow_nan,
+    )
+    write_bytes_atomic(
+        path,
+        (text + "\n").encode("utf-8"),
+        fsync=fsync,
+        overwrite=overwrite,
+        preserve_mode=preserve_mode,
+        permissions=permissions,
+        preserve_owner=preserve_owner,
+        follow_symlinks=follow_symlinks,
+        retry=retry,
+    )

durablewrite/_options.py

@@ -0,0 +1,79 @@
+"""Fsync levels and the retry policy used when the final rename is blocked."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass, field
+from typing import Literal
+
+FsyncLevel = Literal["none", "file", "full"]
+"""How much to flush to stable storage.
+
+``"none"``: no fsync at all. The write is still atomic for readers and survives
+a crash of the writing process, but not a power loss or kernel crash.
+``"file"``: fsync the temp file before the rename, so the new content is on disk
+before its name can point at it.
+``"full"``: ``"file"`` plus an fsync of the parent directory after the rename, so
+the rename itself is durable. Windows has no directory fsync, so there
+``"full"`` behaves like ``"file"``.
+"""
+
+_LEVELS: dict[str, tuple[bool, bool]] = {
+    "none": (False, False),
+    "file": (True, False),
+    "full": (True, True),
+}
+
+
+def resolve_fsync(fsync: FsyncLevel | None, durable: bool, fsync_dir: bool) -> tuple[bool, bool]:
+    """Return ``(sync_file, sync_dir)``; an explicit ``fsync`` wins over the flags."""
+    if fsync is None:
+        return durable, fsync_dir
+    try:
+        return _LEVELS[fsync]
+    except KeyError:
+        raise ValueError(f"fsync must be one of {sorted(_LEVELS)!r}, got {fsync!r}") from None
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Bounded exponential backoff for a rename that a Windows lock blocks.
+
+    Only transient Windows lock errors are retried (see
+    :class:`~durablewrite.SharingViolationError`). Every other error, including
+    a read-only target and any POSIX ``EACCES``, is raised on the first attempt.
+    With the defaults the writer waits at most about 1.1 seconds in total.
+
+    ``max_attempts`` counts every rename attempt, so ``1`` disables retrying.
+    The wait before attempt ``n + 1`` is ``initial_delay * multiplier**(n - 1)``,
+    capped at ``max_delay``. ``sleep`` is injectable for tests.
+    """
+
+    max_attempts: int = 8
+    initial_delay: float = 0.01
+    multiplier: float = 2.0
+    max_delay: float = 0.5
+    sleep: Callable[[float], None] = field(default=time.sleep, compare=False, repr=False)
+
+    def __post_init__(self) -> None:
+        if self.max_attempts < 1:
+            raise ValueError("max_attempts must be at least 1")
+        if self.initial_delay < 0 or self.max_delay < 0:
+            raise ValueError("delays must not be negative")
+        if self.multiplier < 1:
+            raise ValueError("multiplier must be at least 1")
+
+    def delays(self) -> Iterator[float]:
+        """Yield the wait before each retry: ``max_attempts - 1`` values."""
+        delay = self.initial_delay
+        for _ in range(self.max_attempts - 1):
+            yield min(delay, self.max_delay)
+            delay *= self.multiplier
+
+
+DEFAULT_RETRY = RetryPolicy()
+"""The policy used when none is given: 8 attempts, about 1.1 seconds at most."""
+
+NO_RETRY = RetryPolicy(max_attempts=1)
+"""Fail on the first blocked rename."""

durablewrite/_replace.py

@@ -0,0 +1,94 @@
+"""Publishing the finished temp file under the target name, with bounded retry."""
+
+from __future__ import annotations
+
+import errno
+import os
+import stat
+from contextlib import suppress
+
+from ._errors import SharingViolationError
+from ._fs import try_remove
+from ._options import RetryPolicy
+
+# ERROR_ACCESS_DENIED, ERROR_SHARING_VIOLATION, ERROR_LOCK_VIOLATION.
+_TRANSIENT_WINERRORS = frozenset({5, 32, 33})
+
+
+def _is_read_only(path: str) -> bool:
+    try:
+        attributes = getattr(os.stat(path), "st_file_attributes", 0)
+    except OSError:
+        return False
+    return bool(attributes & stat.FILE_ATTRIBUTE_READONLY)
+
+
+def _is_transient(exc: OSError, target: str) -> bool:
+    """True for a Windows lock that may clear by itself, never for a real denial."""
+    if os.name != "nt" or not isinstance(exc, PermissionError):
+        return False
+    if getattr(exc, "winerror", None) not in _TRANSIENT_WINERRORS:
+        return False
+    return not _is_read_only(target) and not os.path.isdir(target)
+
+
+def _create_new(tmp: str, target: str) -> None:
+    """Move ``tmp`` to ``target`` only if ``target`` does not exist, atomically.
+
+    POSIX ``rename`` always overwrites, so a hard link is used instead: ``link``
+    fails with ``EEXIST`` if the name is taken. On Windows ``MoveFileExW``
+    without ``MOVEFILE_REPLACE_EXISTING`` fails the same way.
+    """
+    if os.name == "nt":
+        os.rename(tmp, target)
+        return
+    os.link(tmp, target)
+    with suppress(FileNotFoundError):
+        os.remove(tmp)
+
+
+def publish(tmp: str, target: str, *, overwrite: bool, retry: RetryPolicy) -> None:
+    """Rename ``tmp`` onto ``target``, retrying transient Windows locks only."""
+    move = os.replace if overwrite else _create_new
+    delays = retry.delays()
+    attempt = 1
+    while True:
+        try:
+            move(tmp, target)
+            return
+        except OSError as exc:
+            if not _is_transient(exc, target):
+                raise
+            delay = next(delays, None)
+            if delay is None:
+                error = SharingViolationError(
+                    errno.EACCES,
+                    f"rename kept failing with a sharing, lock or access-denied error "
+                    f"after {attempt} attempts (is another process holding the file open?)",
+                    target,
+                )
+                error.attempts = attempt
+                raise error from exc
+            retry.sleep(delay)
+            attempt += 1
+
+
+def remove_temp(tmp: str, retry: RetryPolicy) -> bool:
+    """Remove the temp file on an error path, waiting out Windows locks.
+
+    Never raises, so it cannot mask the error being handled. Returns False if
+    the file is left behind (still locked, or another error); such files are
+    what :func:`~durablewrite.cleanup_temp_files` reclaims.
+    """
+    delays = retry.delays()
+    while True:
+        outcome = try_remove(tmp)
+        if outcome is not None:
+            return outcome
+        delay = next(delays, None)
+        if delay is None:
+            return False
+        try:
+            retry.sleep(delay)
+        except Exception:
+            return False

durablewrite-0.2.0.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.5
+Name: durablewrite
+Version: 0.2.0
+Summary: Durable, cross-platform atomic file writes: temp-same-dir plus os.replace plus file and dir fsync
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/durablewrite
+Project-URL: Issues, https://github.com/JaviLianes8/durablewrite/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/durablewrite/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: atomic,crash-safe,durable,file,fsync,os.replace,write
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# durablewrite
+
+Durable, cross-platform atomic file writes for Python. Data goes to a temp file
+in the same directory, is flushed and fsynced, then moved onto the target with
+`os.replace`, and the directory is fsynced. A reader never sees a half-written
+file, and a crash leaves either the previous version or the complete new one.
+
+Typed, standard library only, Python 3.10+, Windows and POSIX.
+
+## Install
+
+```
+pip install durablewrite
+```
+
+## Usage
+
+```python
+from durablewrite import atomic_write, write_bytes_atomic, write_json_atomic, write_text_atomic
+
+# One-shot helpers.
+write_text_atomic("notes.txt", "hello\n")
+write_bytes_atomic("snapshot.bin", b"\x00\x01\x02")
+write_json_atomic("config.json", {"ready": True})  # serialised before any file is touched
+
+# Stream into a file: it is replaced only if the block finishes without an error.
+with atomic_write("report.csv") as f:
+    for row in rows:
+        f.write(row + "\n")
+
+with atomic_write("image.png", "wb") as f:
+    f.write(data)
+```
+
+### Options (on every writer)
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `fsync` | `"full"` | `"none"`, `"file"` (fsync the data) or `"full"` (data and directory) |
+| `overwrite` | `True` | `False`: create only if absent, atomically, else `FileExistsError` |
+| `preserve_mode` | `True` | keep the permission bits of the file being replaced (POSIX) |
+| `permissions` | `None` | explicit permission bits, e.g. `0o600` |
+| `preserve_owner` | `False` | keep uid and gid of the replaced file (POSIX) |
+| `follow_symlinks` | `True` | write through a symlink and keep it, or replace the link itself |
+| `retry` | `DEFAULT_RETRY` | bounded retry while Windows reports the target locked |
+
+New files get `0o666` minus your umask, exactly like `open()`. When the final mode
+comes from `permissions` or from the replaced file, the temp file is created as
+`0o600`, so a secret is never readable by others while it is being written.
+
+```python
+from durablewrite import NO_RETRY, RetryPolicy, SharingViolationError, write_text_atomic
+
+write_text_atomic("cache.txt", payload, fsync="none")  # atomic, not durable
+write_text_atomic("token", secret, permissions=0o600, overwrite=False)
+
+try:
+    write_text_atomic("held.txt", "x", retry=RetryPolicy(max_attempts=20, max_delay=0.2))
+except SharingViolationError as exc:  # a PermissionError; target untouched
+    print("still locked after", exc.attempts, "attempts")
+```
+
+A writer that is killed mid-write cannot remove its temp file. Clean those up
+at startup:
+
+```python
+from durablewrite import cleanup_temp_files
+
+cleanup_temp_files("data/", older_than=3600)  # only *.dwtmp files written by durablewrite
+```
+
+## Command line
+
+`durablewrite TARGET` writes standard input to TARGET atomically, like
+`sponge`. TARGET is replaced only after the input ends.
+
+```
+sort names.txt | durablewrite names.txt
+jq '.debug = true' config.json | durablewrite --json config.json
+echo "one more line" | durablewrite --append notes.txt
+printf 's3cret' | durablewrite --permissions 600 --no-overwrite token.txt
+```
+
+Options: `--append`, `--json` (refuse invalid JSON), `--fsync {none,file,full}`,
+`--no-overwrite`, `--permissions OCTAL`, `--no-follow-symlinks`,
+`--attempts N`. Errors go to standard error with exit status 1, and TARGET is
+left as it was. If TARGET was replaced but its directory could not be fsynced,
+the exit status is 3. `python -m durablewrite` works too.
+
+On Windows, redirecting TARGET into the command (`durablewrite f < f`) is refused,
+because the shell keeps the redirected file open and that blocks the rename; pipe
+it instead (`type f | durablewrite f`). Concurrent `--append` runs on one file may
+lose each other's lines: each run is atomic, but they do not merge.
+
+## Guarantees and limits
+
+The short version (details and sources in [GUIDE.md](GUIDE.md)):
+
+- **Atomic for readers and against process crashes** on local filesystems,
+  Windows and POSIX. Exercised by a seeded test that kills a writer process at
+  random moments and by a multi-process concurrent writer test.
+- **Durable against power loss** on Linux with `fsync="full"`. On macOS, `fsync`
+  does not flush the drive cache (`F_FULLFSYNC` is not issued). On Windows the
+  file data is flushed but a directory cannot be fsynced.
+- **Windows**: `os.replace` is `MoveFileExW`, not documented as atomic by
+  Microsoft; tested on NTFS, not guaranteed on FAT or network shares. An open
+  handle elsewhere blocks the rename; it is retried for about a second by
+  default, then `SharingViolationError` is raised. While a rename is in flight,
+  a concurrent `open()` of the target can fail with `PermissionError`; readers
+  that poll should retry. A read-only target cannot be replaced on Windows.
+- **After the rename**, a failing directory fsync raises `DirectorySyncError`:
+  the new content is in place, but the rename may not survive a power loss.
+- Replacing a file creates a new one: other hard links keep the old content,
+  and extended attributes, ACLs and alternate data streams are not copied.
+
+## Why
+
+Writing a file in place can corrupt it: a crash, a full disk or a concurrent
+reader can catch it half-written. The safe pattern (temp file in the same
+directory, fsync, `os.replace`, fsync the directory) is well known but fiddly
+to get right on every platform.
+
+The options that existed each fall short:
+
+- `atomicwrites`, the de-facto package, was **archived by its author in 2022**
+  and takes no fixes.
+- `boltons.fileutils.atomic_save` has **no Windows support**.
+- The `atomicfile` and `atomicwrite` packages on PyPI are **abandoned** (last
+  releases in 2020 and 2015) and neither is typed.
+- `safewrite` is minimal and obscure.
+
+`durablewrite` does the full sequence, keeps permissions, handles Windows
+sharing violations, documents exactly what each platform guarantees, and ships
+a command-line tool.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

durablewrite-0.2.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+durablewrite/__init__.py,sha256=VfuwRzlq3Pd0168dfx_bT2Uajwtl6BHXu94ssKVzAcQ,743
+durablewrite/__main__.py,sha256=76Vu0YuiXneRegw-5Z9nbhwXZvVp8DjXQ4ewyh-cKEw,130
+durablewrite/_atomic.py,sha256=YyhVq80a60e_cW8W0q6uVirA-Ny3YdK_a7Ir6J8WiTs,5948
+durablewrite/_cleanup.py,sha256=8_MRhgI1Pa1IJqr0lE_FJjSwDWw6UNpe-TYjy332RQM,2444
+durablewrite/_cli.py,sha256=IpOX1_uAojRgvSyUUJFwaJ53Kolxip0j7kZ18svcuzk,6280
+durablewrite/_errors.py,sha256=Axi1R7WyklnEQ6E22vEQGtT0rAFasR1xjXRz9ilWG7Q,1725
+durablewrite/_fs.py,sha256=ogn0-4qxl00nmr9EgNcI36c5mY4bunJ5RQULcAcedLc,4534
+durablewrite/_helpers.py,sha256=BmfpB6JWNe6Hxbcg4IeRwZqbOCzwXJbYd-vaWAmU8Js,3817
+durablewrite/_options.py,sha256=PZst3wxioPPZta817l9UhpiLdZD1PuGTBEL5ii8BILI,2985
+durablewrite/_replace.py,sha256=e8wOUawCPYgJ-iZy1DohNePP3ng5q4fpXL2Kt5B0dNw,3147
+durablewrite/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+durablewrite-0.2.0.dist-info/METADATA,sha256=pF_BXdNjWmD1sOB3oxPuZzw7tAyS4MweSAuC1ePVjiE,7181
+durablewrite-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+durablewrite-0.2.0.dist-info/entry_points.txt,sha256=R9sqjd-QNJ7wSm-zu_uJbtBSuvssxwDU9XFa6bM9LGs,56
+durablewrite-0.2.0.dist-info/licenses/LICENSE,sha256=wirD5nCA2aQa5UusK_1YHLBogI3CGcw23xAnulp3L_U,1091
+durablewrite-0.2.0.dist-info/RECORD,,

durablewrite-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

durablewrite-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+durablewrite = durablewrite._cli:main

durablewrite-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.