durablewrite 0.2.0__tar.gz → 1.0.0__tar.gz

{durablewrite-0.2.0 → durablewrite-1.0.0}/.gitignore

@@ -10,3 +10,5 @@ dist/
 .ruff_cache/
 .coverage
 htmlcov/
+tests/oracle/*
+!tests/oracle/MANIFEST.json

durablewrite-1.0.0/CHANGELOG.md

@@ -0,0 +1,139 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-10-16
+
+The public API is now stable: the twelve names in `durablewrite.__all__`, their
+parameters, defaults and error types, the temp file naming scheme that
+`cleanup_temp_files` relies on, and the command line options and exit statuses
+follow Semantic Versioning from here on.
+
+### Changed
+
+- `fsync="full"` (the default) on Windows renames with `MoveFileExW` and
+  `MOVEFILE_WRITE_THROUGH`, so the rename itself is written to disk before the
+  call returns; `"file"` and `"none"` keep plain `os.replace`.
+- On macOS every flush uses `F_FULLFSYNC`, falling back to `fsync` where the
+  filesystem refuses it.
+- All arguments are checked when a writer is called, before any file is
+  touched, instead of when the `with` block is entered.
+- Error messages no longer repeat the refused value; the command line quotes at
+  most 40 characters of the values it checks and cuts every error or warning
+  message after its prefix to 120 characters, keeping its start and its end.
+- On/off options (`overwrite`, `durable`, `fsync_dir`, `preserve_mode`,
+  `preserve_owner`, `follow_symlinks`) accept only `True` or `False`, and a `mode`
+  or `fsync` that is not a string raises `TypeError`: before, any value was taken
+  by truthiness, so `overwrite="no"` overwrote the file.
+- `atomic_write` is typed per mode: `IO[str]` for `"w"`, `IO[bytes]` for `"wb"`
+  (`IO[Any]` only for a mode that is not a literal).
+- `cleanup_temp_files` also removes read-only temp files on Windows, and
+  `older_than=0` removes every matching temp file whatever its time (on Windows
+  with Python 3.10 to 3.12 a file just written could look newer than the clock
+  and be skipped).
+- Errors raised before the block runs name the path as it was given (for a
+  followed symlink, the file it points to); errors from
+  the rename name the target as an absolute path, since a relative target is
+  pinned to the working directory when the write starts.
+- A `retry` that is not a `RetryPolicy` raises `TypeError` (0.2.0 raised
+  `AttributeError` and left a temp file).
+- The `dev` extra is replaced by `requirements-dev.txt`.
+
+### Fixed
+
+- `cleanup_temp_files(older_than=float("nan"))` removed every temp file,
+  including those of running writers; a NaN or infinite age, a non-finite `now`
+  and non-number ages now raise.
+- `RetryPolicy` accepted NaN and infinite delays, which made a blocked write
+  fail with an unrelated error and leave its temp file behind, non-integer or
+  `bool` attempts and a `sleep` that is not callable; these now raise
+  `TypeError` or `ValueError`.
+- A FIFO, device or socket target was silently replaced by a regular file
+  (`durablewrite /dev/null` as root replaced the device; `--append` on a FIFO
+  hung); it now raises `OSError` with `EINVAL`.
+- Permission bits were set on the temp file by name; on POSIX they now go
+  through the descriptor (`fchmod`), so a temp name swapped for a symlink cannot
+  redirect them.
+- A text wrapper that failed to build closed the file descriptor twice and hid
+  its own error behind `EBADF`; codecs that are not text encodings (`hex`) are now
+  refused up front with `LookupError`.
+- An interrupt between creating the temp file and wrapping it left the
+  descriptor open, so on Windows the temp file could not be removed.
+- `--json` refused valid JSON with integers longer than 4300 digits.
+- On Windows a name with `:` wrote to an alternate data stream and left an empty
+  file behind; it now raises `ValueError`.
+- `RetryPolicy` accepted delays so long that `time.sleep` overflowed; delays are
+  now limited to one day.
+- `bytes` paths, paths containing NUL, `permissions` outside `0..0o7777`,
+  `permissions=True`, unknown encodings and invalid `newline` values failed late
+  or with unrelated errors; they now raise `TypeError`, `ValueError` or `LookupError` up front.
+
+### Added
+
+- Ground truth in the test suite: kill-at-every-call tests on every platform, a
+  Linux system call tracer, 120 scenarios recorded from `atomicwrites` 1.4.1 on
+  Windows and Linux, and a manifest of the cited OS documentation.
+- Doctests for every public name, seeded fuzz tests and linear-time checks.
+
+## [0.2.0] - 2026-10-14
+
+### Added
+
+- `write_json_atomic(path, obj, ...)`: serialises before touching the disk and
+  writes UTF-8 JSON with a trailing newline and LF line endings. `NaN` and
+  infinities are refused unless `allow_nan=True`.
+- `fsync="none" | "file" | "full"` on every writer, with the `FsyncLevel` type.
+  The `durable` and `fsync_dir` flags keep working.
+- `overwrite=False`: atomic create-if-absent (`link` on POSIX, `MoveFileExW`
+  without the replace flag on Windows).
+- `preserve_mode` (default on), `permissions` and `preserve_owner` options.
+- `follow_symlinks` (default on): writing through a symlink updates the file it
+  points to and keeps the link.
+- `RetryPolicy`, `DEFAULT_RETRY` and `NO_RETRY`: bounded backoff when a Windows
+  sharing or lock violation blocks the rename.
+- `DurableWriteError` (an `OSError`), `SharingViolationError` (a
+  `PermissionError`) and `DirectorySyncError` (the file was replaced but its
+  directory could not be fsynced).
+- `cleanup_temp_files(directory, older_than=..., target=...)` for temp files
+  left by killed writers.
+- `durablewrite` command line tool (also `python -m durablewrite`): writes
+  standard input to a file atomically, with `--append`, `--json`, `--fsync`,
+  `--no-overwrite`, `--permissions`, `--no-follow-symlinks` and `--attempts`.
+  Exit status 1 on errors, 3 when the file was replaced but not fully synced.
+- `GUIDE.md` with the write protocol, per-platform guarantees and sources.
+
+### Changed
+
+- Temp files are named `.<name>.<8 hex digits>.dwtmp` so they can be cleaned up
+  safely.
+- Writing through a symlink no longer replaces the link with a regular file
+  (pass `follow_symlinks=False` for the old behaviour).
+
+### Fixed
+
+- New files were created with mode `0600` and replaced files lost their mode;
+  new files now honour the umask like `open()` and replaced files keep their
+  permission bits.
+- Very long file names no longer overflow the name limit when the temp name is
+  built.
+- Writing to an existing directory raises `IsADirectoryError` before any temp
+  file is created, and a path ending with a separator raises `ValueError`.
+- When the final mode is restricted (explicit `permissions` or a replaced
+  private file) the temp file is `0600` while it is written.
+- On Windows, removal of a temp file that is briefly locked is retried.
+
+## [0.1.0] - 2026-10-11 (not published)
+
+### Added
+
+- `atomic_write(path, mode, *, encoding, newline, durable, fsync_dir)` context
+  manager: writes to a temp file in the target directory, flushes and fsyncs it,
+  then moves it onto the target with `os.replace` and fsyncs the directory.
+- `write_text_atomic(path, text, encoding, *, newline, durable, fsync_dir)` and
+  `write_bytes_atomic(path, data, *, durable, fsync_dir)` one-shot helpers.
+- Durable by default (file and directory fsync), both switchable off.
+- Correct on Windows and POSIX; typed, zero runtime dependencies.

durablewrite-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Thanks for taking the time. This project keeps a small, predictable shape.
+
+## Setup
+
+```
+pip install -r requirements-dev.txt
+python scripts/fetch_oracles.py   # optional: reference library and cited pages
+```
+
+## Before you open a pull request
+
+- Keep public API in `src/durablewrite/__init__.py`; internals live in `_`-prefixed modules.
+- Add a test for the behaviour you change. Tests run against the real filesystem and
+  real child processes; only the retry `sleep` and, in a few contract tests, single
+  OS calls are replaced to observe what is asked of the operating system.
+- Run the gate: `ruff format --check .`, `ruff check .`, `mypy --strict src tests` and
+  `pytest` (the repository has `scripts/check.ps1` for this). The multi-process and
+  packaging tests are marked `slow`; `pytest -m "not slow"` skips them while
+  iterating, but the full suite must pass before a commit. Run it on Windows and on
+  Linux; the system call tests need Linux and `gcc`.
+- The crash and fuzz tests are seeded: set `DURABLEWRITE_CRASH_SEED`,
+  `DURABLEWRITE_CRASH_ITERATIONS` or `DURABLEWRITE_FUZZ_SEED` to explore further.
+- Material fetched by `scripts/fetch_oracles.py` stays out of the repository; only
+  `tests/oracle/MANIFEST.json` is tracked.
+- One logical change per commit, imperative subject line.
+
+Open an issue first if the change is large or shifts the public API.

durablewrite-1.0.0/GUIDE.md

@@ -0,0 +1,309 @@
+# durablewrite guide
+
+This guide explains what `durablewrite` does on every write, what it guarantees
+on each platform, and where those guarantees stop. Each claim names its source
+or the test in this repository that exercises it.
+
+## The write protocol
+
+For `atomic_write(path)` and every helper built on it:
+
+1. **Check the arguments** when the writer is called, before any file is
+   touched (see "Errors" below).
+2. **Resolve the target.** If `path` is a symlink and `follow_symlinks=True`
+   (the default), the file it points to becomes the target, so the link keeps
+   working. With `follow_symlinks=False` the link itself is replaced by a
+   regular file. An existing directory is rejected with `IsADirectoryError`, a
+   FIFO, device or socket with `OSError` (`EINVAL`) so it is never swapped for a
+   regular file, and
+   with `overwrite=False` an existing name is rejected with `FileExistsError`,
+   both before the block runs.
+3. **Create a temp file in the target's own directory**, named
+   `.<name>.<8 hex digits>.dwtmp`, with `O_CREAT | O_EXCL`. A new file is created
+   with mode `0o666`, so the process umask applies exactly as it does for
+   `open()`. When the final mode comes from `permissions` or from the replaced
+   file, the temp file starts as `0o600` and is widened only after the data is
+   written, so restricted content is never readable by others in between. Names
+   longer than 48 characters keep a readable head plus a hash of the full name,
+   so the temp name stays within the 255-byte limit. The same directory means
+   the same filesystem, which the rename needs: Python documents that
+   `os.replace` may fail across filesystems [1].
+4. **Write** your data into it.
+5. **Set metadata.** With `preserve_owner=True` (POSIX) the uid and gid of the
+   old file are copied first, then the permission bits: either `permissions` or,
+   with `preserve_mode=True` (the default), the bits of the old file. On POSIX
+   both go through the open descriptor (`fchown`, `fchmod`), so a temp name
+   swapped for a symlink by someone else cannot redirect them.
+6. **Flush the temp file to disk** (`fsync="file"` or `"full"`): `fsync` on
+   Linux, `F_FULLFSYNC` on macOS, `FlushFileBuffers` on Windows. This must come
+   before the rename, or the new name can reach the disk before the data it
+   points to, which is how ext4 left zero-length files after a crash until it
+   added a heuristic for that pattern [3][4].
+7. **Rename** the temp file onto the target. With `overwrite=False` a
+   create-only rename is used instead (see below).
+8. **Make the rename durable** (`fsync="full"`). On POSIX the parent directory is
+   fsynced: the Linux `fsync(2)` page says a file fsync does not by itself make
+   the directory entry durable, and asks for an fsync of the directory [2][3].
+   On Windows the rename of step 7 is made with `MOVEFILE_WRITE_THROUGH`, which
+   Microsoft documents as not returning until the move is on the disk [6].
+
+If anything raises before step 7 completes, the temp file is removed and the
+target is untouched. That includes exceptions inside your `with` block and
+`KeyboardInterrupt`.
+
+## What is guaranteed, per platform
+
+| Promise | Linux / macOS (local fs) | Windows (local NTFS) |
+| --- | --- | --- |
+| Readers see the old or the complete new file, never a mix | Yes, `rename(2)` replaces the name atomically [5][12] | Yes on NTFS in our tests; Microsoft does not call the rename atomic [6] |
+| A killed writer leaves the old or the new file, never a partial one | Yes (tested at every call) | Yes (tested at every call) |
+| New content survives power loss once the call returns (`"full"`) | Linux: data and directory fsynced. macOS: `F_FULLFSYNC` [8] | Data flushed [7]; rename written through [6] |
+| Permission bits kept on replace | Yes (`preserve_mode`) | Not applicable; see below |
+| Owner kept on replace | Opt-in (`preserve_owner`), needs privilege to change uid | No |
+| Replace while another process has the target open | Yes; the reader keeps the old inode | Retried, then `SharingViolationError` |
+| A reader can always open the target | Yes | No: an `open()` racing a rename can fail for a moment with `PermissionError` or, rarely, `FileNotFoundError` (never torn); readers that poll should retry both |
+| Replace a read-only target | Yes, if the directory is writable | No, `PermissionError` (not retried) |
+
+### Process crash versus power loss
+
+A process crash is tested directly. `tests/test_crash_points.py` runs a writer
+that kills itself with no cleanup right before and right after each file system
+call it makes, for every call, on Windows and POSIX. `tests/test_linux_trace.py`
+does the same on Linux one level lower: an `LD_PRELOAD` library
+(`tests/trace/dwtrace.c`) logs the real libc calls (`open`, `write`, `fsync`,
+`rename`, `link`, `unlink`) and sends `SIGKILL` at each boundary. In every case
+the target holds the old content until the rename has returned and the new
+content from then on, and any leftover temp file is one that
+`cleanup_temp_files` removes. `tests/test_crash.py` also kills writers at random
+moments mid-write.
+
+No portable test can cut the power, so durability against power loss rests on
+the documented calls above and on the filesystem honouring them [3].
+
+### Linux
+
+`fsync="full"` follows the sequence recommended in "Ensuring data reaches disk"
+[3]: fsync the file, rename, fsync the directory. The trace test records exactly
+that order. Do not rely on ext4's `auto_da_alloc` heuristic for "replace via
+rename" [4]; it is an ext4 mount option that can be turned off, not a promise of
+the rename itself. If the directory fsync raises (some network and FUSE filesystems refuse it,
+and it fails when the directory is writable but not readable), the new content is
+already in place and `DirectorySyncError` is raised so you know the rename may
+not be durable (`tests/test_hardening.py`).
+
+### macOS
+
+Apple documents that `fsync` hands the data to the drive without asking the
+drive to empty its own write cache, and offers the `F_FULLFSYNC` fcntl for that
+[8]. `durablewrite` issues `F_FULLFSYNC` for the file and for the directory, and
+falls back to `fsync` on a filesystem that refuses it. This is the same choice
+`atomicwrites` made. macOS was not part of this release's test runs; the code
+path is pinned by `tests/test_contract_platform.py`.
+
+### Windows
+
+- `os.fsync` calls the C runtime's `_commit` [1][9], which forces the file to
+  disk; on Windows 11 a hook on the C runtime showed `_commit` calling
+  `FlushFileBuffers` [7] (observed, not documented on the `_commit` page).
+- With `fsync="full"`, the rename is `MoveFileExW` with
+  `MOVEFILE_WRITE_THROUGH` (plus `MOVEFILE_REPLACE_EXISTING` unless
+  `overwrite=False`) [6], as `atomicwrites` does. With `"file"` or `"none"` it is
+  plain `os.replace`, which is `MoveFileExW` without write-through.
+- There is no directory fsync through the APIs Python exposes; write-through
+  takes its place.
+- Microsoft does not document the rename as atomic. On a local NTFS volume it is
+  a single metadata operation and our tests never observed a torn target. A
+  reader opening the name while it is being replaced can, rarely, get
+  `FileNotFoundError` (about 1 open in 1,000 to 2,000 with four writers
+  hammering one file); 0.2.0 behaved the same. On FAT volumes and SMB shares the behaviour depends on the filesystem
+  or server and is not guaranteed.
+- The rename fails with `ERROR_ACCESS_DENIED`, `ERROR_SHARING_VIOLATION` or
+  `ERROR_LOCK_VIOLATION` while any process holds the target open without
+  `FILE_SHARE_DELETE` [10]. Python's `open()` does not pass that flag, and
+  antivirus scanners and the search indexer briefly open new files. These errors
+  are retried with bounded backoff (`RetryPolicy`, about 1.1 seconds by default).
+  A read-only target is never retried. Several processes replacing one file
+  while others read it can keep it locked for longer than that on a slow or busy
+  machine, and so can many writers of one file on their own (an adversarial run
+  of 16 threads saw a few blocked renames in 3,200); give such writers a larger
+  `RetryPolicy`. When the budget runs out,
+  `SharingViolationError` is raised and the target is untouched
+  (`tests/test_sharing.py`). A directory ACL that denies the rename produces the
+  same error code and ends the same way.
+- The temp file can itself be held open (an antivirus scan of the fresh file).
+  On every error path its removal is retried under the same `RetryPolicy`; if it
+  is still locked after that, it is left for `cleanup_temp_files`, which also
+  clears a read-only attribute before removing.
+- Permission bits do not exist on Windows. `permissions` only toggles the
+  read-only attribute and `preserve_mode` does nothing. The new file inherits the
+  ACL of its directory; an explicit ACL on the old file is not copied.
+
+### Why not `ReplaceFileW`
+
+`ReplaceFileW` [11] keeps the replaced file's ACL, attributes and creation time,
+but it is built around an existing file to replace (in our tests on Windows 11
+it failed when the target was missing) and it can fail half way: Microsoft lists a
+result, `ERROR_UNABLE_TO_MOVE_REPLACEMENT_2`, in which the replaced file is left
+under another name. A primitive whose failure mode removes the target conflicts
+with the core promise, so `durablewrite` uses `MoveFileExW`.
+
+## Create only if absent
+
+`overwrite=False` publishes the complete file only if nothing exists at the
+target, and raises `FileExistsError` otherwise, without a check-then-act race:
+
+- POSIX: `link(temp, target)` fails with `EEXIST` if the name is taken [13], then
+  the temp name is unlinked. The filesystem must support hard links.
+- Windows: `MoveFileExW` without `MOVEFILE_REPLACE_EXISTING` fails with error
+  183 (`FileExistsError`), observed on NTFS (`tests/test_contract_platform.py`).
+
+An existing name is refused before the block runs; a name that appears while
+the block runs is refused by the rename. `tests/test_overwrite.py` races six
+processes for one name and checks that exactly one wins.
+
+## Symlinks
+
+The default (`follow_symlinks=True`) writes to the file the link points to and
+creates the temp file beside that file, so the rename never crosses a
+filesystem even when the link lives elsewhere. A dangling link creates its
+target. `follow_symlinks=False` replaces the link with a regular file, which is
+what plain `os.replace` (and `atomicwrites`) does; on POSIX this also works when
+the link points to a directory. The replaced link counts as a new file, so it
+does not inherit the mode of whatever it pointed to.
+
+## Side effects of replacing a file
+
+Replacing a file creates a new file, by design. As a consequence:
+
+- Other hard links to the old file keep the old content.
+- The inode (POSIX) or file ID (Windows) changes. Programs that follow a file by
+  handle, such as `tail -f` without `-F`, keep reading the old file.
+- Extended attributes, POSIX ACLs and Windows alternate data streams of the old
+  file are not copied.
+
+## Leftover temp files
+
+A writer that is killed between creating its temp file and renaming it cannot
+clean up. `cleanup_temp_files(directory, older_than=3600)` removes only regular
+files matching `.<name>.<8 hex digits>.dwtmp` older than the given age, by
+modification time. A writer that keeps its temp file open for longer than that
+age could lose it, so choose an age longer than your slowest write. With
+`target=`, only temp files of that exact target name are considered. The age
+must be a finite number of seconds, not negative: `NaN` once made every temp
+file look stale, so it is refused.
+
+## Errors
+
+| Error | When |
+| --- | --- |
+| `TypeError` | a `bytes` path, an on/off option that is not `True` or `False`, or another argument of the wrong type |
+| `ValueError` | a bad `mode`, `fsync`, `newline`, `permissions`, retry setting (delays from 0 to one day) or age; an empty path, a NUL in it, one ending with a separator, or on Windows a name with `:` (an alternate data stream) |
+| `LookupError` | an unknown `encoding`, or a codec that is not a text encoding (`hex`) |
+| `IsADirectoryError` | the target is a directory |
+| `OSError` (`EINVAL`) | the target is a FIFO, device or socket |
+| `FileExistsError` | `overwrite=False` and the name exists |
+| `SharingViolationError` | Windows kept the rename blocked for the whole retry budget (a `PermissionError`) |
+| `DirectorySyncError` | the file was replaced, but the directory fsync failed (POSIX, `"full"`) |
+| other `OSError` | whatever the operating system reports: a missing directory, no space, no permission |
+
+The first three are raised when the writer is called, before any file is
+touched. Messages are short and never repeat the value they refuse.
+`DurableWriteError` is the base of the two errors `durablewrite` raises itself
+and is an `OSError`, so existing `except OSError` code keeps working.
+
+## Command line
+
+`durablewrite TARGET` copies standard input into TARGET with the protocol above,
+like `sponge` from moreutils. TARGET is replaced only after standard input ends,
+so `sort f | durablewrite f` is safe on every platform, and
+`durablewrite --append f < f` works on POSIX. On Windows the shell (and the
+console-script launcher) keep a redirected file open without
+`FILE_SHARE_DELETE`, which blocks the rename, so the command detects that
+standard input is TARGET and refuses at once; pipe the file instead.
+
+Exit status: 0 on success; 1 on any error, including a usage error, with TARGET
+left as it was; 3 when TARGET was replaced but its directory could not be
+fsynced; 130 when interrupted. `--json` accepts only strict JSON (no `NaN` or
+`Infinity`). Each `--append` run is atomic, but two concurrent runs on the same
+file can lose one run's data, because each starts from the content it read.
+
+## How this was checked
+
+- **Documentation**: `tests/oracle/MANIFEST.json` lists every page cited below
+  with its URL, fetch date, size and hash; `scripts/fetch_oracles.py` downloads
+  them into a local folder that is never committed, and `tests/test_sources.py`
+  checks that each still names the calls and flags this guide relies on.
+- **System calls**: `tests/test_linux_trace.py` (Linux, needs gcc) records the
+  real call order for each fsync level and kills the writer at every call.
+- **Reference library**: `atomicwrites` 1.4.1 ran 120 scenarios (new file,
+  replace, create-only, directory, symlink, dangling link, failing block, text and
+  binary) on Windows and Linux; `tests/fixtures/atomicwrites-*.json` is its
+  recorded output, and `tests/test_reference.py` checks that durablewrite matches
+  it wherever a plain file is written, and differs only as this guide says
+  elsewhere. Under the tracer both libraries make the same fsync, rename,
+  directory fsync sequence.
+
+## Upgrading from 0.2
+
+Code that passes the documented argument types keeps working; the differences:
+
+- `fsync="full"` now uses `MOVEFILE_WRITE_THROUGH` on Windows and `F_FULLFSYNC`
+  on macOS.
+- Arguments are checked when the writer is called rather than when the `with`
+  block is entered, and more of them are checked: `bytes` paths, paths with a
+  NUL, `permissions` outside `0..0o7777`, unknown encodings, invalid `newline`
+  values, codecs that are not text encodings, a `retry` that is not a
+  `RetryPolicy`, and on Windows alternate data stream names.
+- A FIFO, device or socket target raises `OSError` (`EINVAL`); 0.2.0 replaced it
+  with a regular file (as root, `durablewrite /dev/null` replaced the device).
+- `RetryPolicy` delays longer than one day are refused.
+- `--json` checks numbers without converting them, so integers longer than 4300
+  digits are accepted.
+- On/off options (`overwrite`, `durable`, `fsync_dir`, `preserve_mode`,
+  `preserve_owner`, `follow_symlinks`) must be `True` or `False`: 0.2.0 took any
+  value by truthiness, so `overwrite="no"` overwrote. A `mode` or `fsync` that is
+  not a string, and `permissions=True`, raise `TypeError`.
+- `RetryPolicy` refuses attempts that are not an `int` (a `bool` included), a
+  `sleep` that is not callable, and delays or multipliers that are NaN, infinite
+  or of the wrong type; `cleanup_temp_files` refuses a NaN or
+  infinite age and a non-finite `now`.
+- `cleanup_temp_files` removes read-only temp files on Windows, and
+  `older_than=0` removes every matching temp file whatever its time.
+- Errors raised before the block runs name the path as given (for a followed
+  symlink, the file it points to); errors from the rename name the absolute
+  target (a relative target is pinned when the write
+  starts).
+- Error messages no longer repeat the refused value. The command line quotes at
+  most 40 characters of the values it checks itself, and every error or warning
+  message it prints after its `durablewrite: error:` prefix is cut to 120
+  characters, keeping its start and its end (where the file name is).
+- `atomic_write` is typed per mode: `IO[str]` for `"w"`, `IO[bytes]` for `"wb"`.
+- The `dev` extra is gone; contributors use `requirements-dev.txt`.
+
+## Sources
+
+Fetched on 2026-10-16.
+
+1. Python documentation, `os.replace` and `os.fsync`:
+   https://docs.python.org/3/library/os.html
+2. Linux `fsync(2)` manual page: https://man7.org/linux/man-pages/man2/fsync.2.html
+3. Jeff Moyer, "Ensuring data reaches disk", LWN.net, 2011:
+   https://lwn.net/Articles/457667/
+4. Linux kernel documentation, ext4 mount options (`auto_da_alloc`):
+   https://docs.kernel.org/admin-guide/ext4.html
+5. POSIX.1-2024, `rename`:
+   https://pubs.opengroup.org/onlinepubs/9799919799/functions/rename.html
+6. Microsoft, `MoveFileExW`:
+   https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-movefileexw
+7. Microsoft, `FlushFileBuffers`:
+   https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-flushfilebuffers
+8. Apple, `fsync(2)` manual page (`F_FULLFSYNC`):
+   https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fsync.2.html
+9. Microsoft, `_commit`:
+   https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/commit
+10. Microsoft, `CreateFileW` (`FILE_SHARE_DELETE`):
+    https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilew
+11. Microsoft, `ReplaceFileW`:
+    https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-replacefilew
+12. Linux `rename(2)` manual page: https://man7.org/linux/man-pages/man2/rename.2.html
+13. Linux `link(2)` manual page: https://man7.org/linux/man-pages/man2/link.2.html

{durablewrite-0.2.0 → durablewrite-1.0.0}/LICENSE

@@ -1,21 +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.
+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.