durablewrite 0.2.0__tar.gz

durablewrite-0.2.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

durablewrite-0.2.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+buy_me_a_coffee: jlianesglrs

durablewrite-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

durablewrite-0.2.0/CHANGELOG.md

@@ -0,0 +1,66 @@
+# 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]
+
+## [0.2.0]
+
+### 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]
+
+### 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-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+Thanks for taking the time. This project keeps a small, predictable shape.
+
+## Setup
+
+```
+pip install -r requirements-dev.txt
+```
+
+## 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; nothing on the write path is mocked. Only the retry `sleep` is
+  injected.
+- Run `scripts/check.ps1` (format, lint, types, tests) and make sure it passes. 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.
+- The crash test is seeded: set `DURABLEWRITE_CRASH_SEED` and
+  `DURABLEWRITE_CRASH_ITERATIONS` to explore other interleavings.
+- One logical change per commit, imperative subject line.
+
+Open an issue first if the change is large or shifts the public API.

durablewrite-0.2.0/GUIDE.md

@@ -0,0 +1,207 @@
+# durablewrite guide
+
+This guide explains what `durablewrite` does on every write, what it guarantees
+on each platform, and where those guarantees stop. Each claim cites 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. **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`.
+2. **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. Same directory
+   means same filesystem, which `rename` needs to be atomic: Python documents
+   that `os.replace` "may fail if src and dst are on different filesystems" [1].
+3. **Write** your data into it.
+4. **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.
+5. **Flush and fsync the temp file** (`fsync="file"` or `"full"`). This must
+   happen before the rename: otherwise the new name can reach disk before the
+   data it points to, which is how ext4 and XFS produced empty or zero-filled
+   files after a crash [3][4][5].
+6. **Rename** the temp file onto the target with `os.replace`. With
+   `overwrite=False`, a create-only rename is used instead (see below).
+7. **Fsync the parent directory** (`fsync="full"`, POSIX only) so the rename
+   itself is on disk. Linux `fsync(2)`: "Calling fsync() does not necessarily
+   ensure that the entry in the directory containing the file has also reached
+   disk. For that an explicit fsync() on a file descriptor for the directory is
+   also needed." [2][3]
+
+If anything raises before step 6 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)` is atomic by POSIX [6] | Yes on NTFS in our tests; not documented as atomic by Microsoft [7] |
+| A killed writer leaves the old or the new file, never a partial one | Yes (tested) | Yes (tested) |
+| New content survives power loss once the call returns (`"full"`) | Linux: yes, file and directory are fsynced. macOS: see below | File data is flushed with `FlushFileBuffers` [8]; the rename is not explicitly flushed |
+| 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 with `PermissionError` (never `FileNotFoundError`, never torn) |
+| Replace a read-only target | Yes, if the directory is writable | No, `PermissionError` (not retried) |
+
+The crash and concurrency rows are exercised by `tests/test_crash.py` and
+`tests/test_concurrency.py`, which run on both Windows (NTFS) and Linux (ext4)
+in this project's local gate.
+
+### Process crash versus power loss
+
+The kill-mid-write test terminates a writer process at random moments (seeded,
+`DURABLEWRITE_CRASH_SEED`) and checks that the target is always a complete,
+checksummed payload. That proves atomicity against a process crash. No portable
+test can cut the power, so durability against power loss rests on the fsync
+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. Do not rely on ext4's
+`auto_da_alloc` heuristic for "replace via rename" [4]; it is a mount option and
+other filesystems such as XFS have no equivalent [5]. 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
+
+On macOS `fsync` hands the data to the drive but does not ask the drive to
+flush its own write cache; Apple documents `F_FULLFSYNC` for that [9].
+`durablewrite` calls `os.fsync` and does not issue `F_FULLFSYNC`, so on macOS
+`"full"` protects against an OS crash but not necessarily against a power loss
+with an unflushed drive cache.
+
+### Windows
+
+- `os.replace` is `MoveFileExW(src, dst, MOVEFILE_REPLACE_EXISTING)` [1][7].
+  Microsoft does not document it as atomic. On a local NTFS volume the rename is
+  a single metadata operation and our tests never observed a torn or missing
+  target. On FAT volumes and SMB shares the behaviour depends on the
+  filesystem or server and is not guaranteed.
+- `os.fsync` calls the CRT `_commit`, which calls `FlushFileBuffers` [8][10].
+- There is no directory fsync on Windows through the APIs Python exposes, so
+  `"full"` behaves like `"file"`. The data of the new file is flushed before
+  the rename; the rename itself becomes durable when NTFS commits its journal.
+- `MoveFileExW` fails with `ERROR_ACCESS_DENIED`, `ERROR_SHARING_VIOLATION` or
+  `ERROR_LOCK_VIOLATION` while any process holds the target open without
+  `FILE_SHARE_DELETE` [11]. 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. 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`.
+- 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` [12] keeps the replaced file's ACL, attributes and creation
+time, but it requires the target to exist and it can fail half way: its
+documented `ERROR_UNABLE_TO_MOVE_REPLACEMENT_2` result leaves the target under
+the backup 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, then the
+  temp name is unlinked. The filesystem must support hard links.
+- Windows: `MoveFileExW` without `MOVEFILE_REPLACE_EXISTING` fails with
+  `ERROR_ALREADY_EXISTS`.
+
+`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` 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 crash test uses it to reclaim every temp file its
+kills leave behind.
+
+## 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. `--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.
+
+## Sources
+
+1. Python documentation, `os.replace` and `os.fsync`:
+   https://docs.python.org/3/library/os.html#os.replace
+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. XFS FAQ, "Why do I see binary NULLS in some files after recovery when I
+   unplugged the power?": https://xfs.org/index.php/XFS_FAQ
+6. POSIX.1-2024, `rename`:
+   https://pubs.opengroup.org/onlinepubs/9799919799/functions/rename.html
+7. Microsoft, `MoveFileExW`:
+   https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-movefileexw
+8. Microsoft, `FlushFileBuffers`:
+   https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-flushfilebuffers
+9. Apple, `fsync(2)` manual page (`F_FULLFSYNC`):
+   https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fsync.2.html
+10. Microsoft, `_commit`:
+    https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/commit
+11. Microsoft, `CreateFileW` (`FILE_SHARE_DELETE`):
+    https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilew
+12. Microsoft, `ReplaceFileW`:
+    https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-replacefilew

durablewrite-0.2.0/IMPROVEMENTS-round.md

@@ -0,0 +1,93 @@
+# Improvements round: durablewrite
+
+This round takes `durablewrite` from a correct but minimal context manager to a
+complete atomic-write toolkit that is honest about what each platform does and
+does not guarantee. Every promise below is backed by a test that runs on the real
+filesystem: no mocked `os.replace`, no mocked `fsync`.
+
+The public API grows additively. `atomic_write`, `write_text_atomic` and
+`write_bytes_atomic` keep their signatures; new behaviour arrives through new
+keyword arguments, new functions and a command-line tool.
+
+## Ranked improvements
+
+### 1. Correct permissions for new and replaced files (correctness, high)
+`tempfile.mkstemp` creates files with mode `0600`, so 0.1.0 silently turned a
+`0644` config or a `0755` script into a private, non-executable file on every
+write. The temp file is now created with `O_CREAT | O_EXCL` and mode `0666`, so
+the process umask applies exactly as it does for `open()`. When the target
+already exists its permission bits are copied onto the temp file before the
+rename (`preserve_mode=True`, the default). `permissions=0o600` sets explicit
+bits, and `preserve_owner=True` copies uid and gid on POSIX.
+
+### 2. Bounded retry on Windows sharing violations (robustness, high)
+On Windows, `os.replace` is `MoveFileExW(MOVEFILE_REPLACE_EXISTING)`, which fails
+with `ERROR_ACCESS_DENIED` or `ERROR_SHARING_VIOLATION` while another process
+holds the target open without `FILE_SHARE_DELETE`. Python's own `open()` does not
+pass that flag, and antivirus scanners and the search indexer open freshly
+written files for a moment. A frozen `RetryPolicy` (attempts, initial delay,
+multiplier, cap, injectable `sleep`) retries only those Windows error codes, never
+a read-only target or a POSIX `EACCES`, and raises a typed
+`SharingViolationError` (a `PermissionError`) when the budget runs out. Removal
+of the temp file is retried under the same policy.
+
+### 3. Explicit fsync levels (clarity, high)
+`fsync="none" | "file" | "full"` replaces the two loosely related booleans with
+one named choice. `full` (the default) fsyncs the temp file before the rename and
+the parent directory after it, which is what ext4 and XFS need for the rename to
+survive power loss. The old `durable` and `fsync_dir` flags keep working. The
+docs state plainly that Windows has no directory fsync and that macOS `fsync`
+does not flush the drive cache.
+
+### 4. JSON helper (convenience, high)
+`write_json_atomic(path, obj, ...)` serialises first, so a value that cannot be
+encoded raises before any file is created, then writes atomically with a trailing
+newline. Defaults suit config files: `indent=2`, UTF-8, `ensure_ascii=False`.
+
+### 5. Atomic create-if-absent (`overwrite=False`) (capability, medium)
+Publishes the complete file only if nothing exists at the target, without a
+check-then-act race: `os.link` on POSIX and a plain `MoveFileExW` without the
+replace flag on Windows both fail atomically when the name is taken. Useful for
+one-time initialisation and lock-free "first writer wins" files.
+
+### 6. Documented symlink policy (correctness, medium)
+Writing through a symlink now updates the file the link points to and keeps the
+link (`follow_symlinks=True`), which is what dotfile managers expect. The temp
+file is created next to the real target, so the rename never crosses a
+filesystem. `follow_symlinks=False` replaces the link itself with a regular file.
+
+### 7. Stale temp file cleanup (operations, medium)
+A process killed mid-write cannot remove its temp file. Temp files now carry a
+distinctive `.dwtmp` suffix and `cleanup_temp_files(directory, older_than=...)`
+removes only those, only once they are older than a chosen age (one hour by
+default).
+
+### 8. Typed errors and early validation (ergonomics, medium)
+`DurableWriteError` is the base of errors the library raises itself and
+subclasses `OSError`, so existing `except OSError` handlers keep working.
+Writing to an existing directory raises `IsADirectoryError` before any temp file
+exists. Long file names no longer overflow the 255-byte name limit when the temp
+name is built.
+
+### 9. A `sponge`-style CLI (tooling, medium)
+`durablewrite TARGET` streams stdin into TARGET atomically, so
+`sort data.txt | durablewrite data.txt` is safe. Flags cover `--append`,
+`--json` (refuse to write invalid JSON), `--fsync`, `--no-overwrite`,
+`--permissions` and `--attempts`. Errors go to stderr with exit status 1.
+
+### 10. Guide with sources and real crash tests (trust, high)
+A `GUIDE.md` explains the write protocol step by step with citations, and the
+test suite proves the promise: a seeded kill-mid-write test that terminates a
+writer process at random moments and checks the target is always a complete old
+or complete new payload, a multi-process concurrent writer test, a held-open
+reader test on Windows, and an end-to-end test that builds a wheel, installs it
+into a throwaway virtual environment and drives the installed `durablewrite`
+script.
+
+## Out of scope this round
+
+- `ReplaceFileW` on Windows. It preserves ACLs and attributes of the replaced
+  file, but it is documented to fail half way (`ERROR_UNABLE_TO_MOVE_REPLACEMENT_2`)
+  and requires the target to exist, so it would weaken the core promise.
+- `F_FULLFSYNC` on macOS. Documented, not issued, because it cannot be exercised
+  by the local test suite.

durablewrite-0.2.0/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.

durablewrite-0.2.0/PKG-INFO

@@ -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/