feno-atomic-write 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,388 @@
1
+ """Replace a file with complete bytes, or leave the previous bytes in place.
2
+
3
+ Every write goes to a temporary file in the destination's own directory, is
4
+ flushed and fsynced, and is then renamed over the destination with `os.replace`.
5
+ A reader therefore sees the whole previous file or the whole new file, never a
6
+ partial write, and a failed write leaves the destination untouched.
7
+
8
+ Two contracts the standard library leaves open are explicit here:
9
+
10
+ - overwrite and create-only. `overwrite=True` (the default) replaces an
11
+ existing file. `overwrite=False` publishes a new file and raises
12
+ FileExistsError rather than replacing one; it publishes through `os.link`,
13
+ so when two writers race the loser raises FileExistsError instead of
14
+ overwriting the winner.
15
+ - durability. `durability` is `none`, `file` (fsync the new bytes before the
16
+ rename), `file+directory` (also fsync the containing directory so the
17
+ rename survives a crash; the default) or `full` (`file+directory`, plus
18
+ macOS F_FULLFSYNC on the new bytes so they reach stable media, not only the
19
+ drive cache). A directory that cannot be fsynced (SMB, FUSE: EINVAL or
20
+ ENOTSUP) is skipped, because the rename has already happened by then.
21
+
22
+ Permissions come from the existing destination unless `mode` is given, so a
23
+ 0600 state file stays 0600 after a replacement. `mode="umask"` instead gives
24
+ every write the fresh default (0666 minus the process umask), as a plain
25
+ `open(path, "w")` on a new file would. A path that is a symlink is
26
+ followed, so its target is replaced and the link survives. `dir_fd` pins both
27
+ the temporary file and the rename to an already-validated directory
28
+ descriptor; the destination name is then relative to that descriptor.
29
+ """
30
+ from __future__ import annotations
31
+
32
+ import errno
33
+ import json
34
+ import os
35
+ import stat
36
+ import sys
37
+ import uuid
38
+ from contextlib import contextmanager
39
+ from typing import Any, BinaryIO, Iterator, TextIO
40
+
41
+ __all__ = [
42
+ "DURABILITIES",
43
+ "Staged",
44
+ "atomic_path",
45
+ "write_bytes",
46
+ "write_json",
47
+ "write_text",
48
+ ]
49
+
50
+ DURABILITIES = ("none", "file", "file+directory", "full")
51
+ _UNSYNCABLE = {errno.EINVAL, errno.ENOTSUP, getattr(errno, "EOPNOTSUPP", errno.ENOTSUP)}
52
+
53
+
54
+ def _resolve(path, dir_fd, follow_symlinks: bool) -> str:
55
+ """Return the name to publish.
56
+
57
+ `follow_symlinks=True` (the default) replaces the link's target and keeps the
58
+ link. `follow_symlinks=False` replaces the link itself, which is what a caller
59
+ publishing a deploy entry needs when the entry may have been swapped for a
60
+ link by another process.
61
+ """
62
+ name = os.fspath(path)
63
+ if dir_fd is not None or not follow_symlinks:
64
+ return name
65
+ return os.path.realpath(name) if os.path.islink(name) else name
66
+
67
+
68
+ def _existing_mode(name, dir_fd) -> int | None:
69
+ """Permissions of the regular file now at `name` (through a link), else None."""
70
+ try:
71
+ status = os.stat(name, dir_fd=dir_fd)
72
+ except (FileNotFoundError, NotADirectoryError):
73
+ return None
74
+ return status.st_mode & 0o7777 if stat.S_ISREG(status.st_mode) else None
75
+
76
+
77
+ def _temporary_name(name) -> str:
78
+ """A fresh name beside `name`, in the same directory (or dir_fd-relative directory)."""
79
+ return os.path.join(os.path.dirname(name), f".{os.path.basename(name)}.{uuid.uuid4().hex}.tmp")
80
+
81
+
82
+ def _sync_file(descriptor, durability) -> None:
83
+ """Flush file bytes per `durability`; `full` adds macOS F_FULLFSYNC."""
84
+ if durability == "none":
85
+ return
86
+ os.fsync(descriptor)
87
+ if durability == "full" and sys.platform == "darwin":
88
+ import fcntl
89
+
90
+ try:
91
+ fcntl.fcntl(descriptor, getattr(fcntl, "F_FULLFSYNC", 51))
92
+ except OSError as error:
93
+ if error.errno not in _UNSYNCABLE:
94
+ raise
95
+
96
+
97
+ def _sync_directory(directory, dir_fd) -> None:
98
+ """Persist a directory entry. Windows has no directory fsync.
99
+
100
+ Runs after the rename, so a filesystem that cannot fsync a directory
101
+ (EINVAL/ENOTSUP on SMB or FUSE) must not turn a finished write into an error.
102
+ """
103
+ try:
104
+ if dir_fd is not None:
105
+ os.fsync(dir_fd)
106
+ elif os.name != "nt":
107
+ descriptor = os.open(directory, os.O_RDONLY)
108
+ try:
109
+ os.fsync(descriptor)
110
+ finally:
111
+ os.close(descriptor)
112
+ except OSError as error:
113
+ if error.errno not in _UNSYNCABLE:
114
+ raise
115
+
116
+
117
+ def _permissions(mode, name, dir_fd) -> int | None:
118
+ """The mode for the new file; None means the process umask decides."""
119
+ if mode == "umask":
120
+ return None
121
+ if mode is not None:
122
+ return mode
123
+ return _existing_mode(name, dir_fd)
124
+
125
+
126
+ def _check(durability, overwrite) -> None:
127
+ if durability not in DURABILITIES:
128
+ raise ValueError(f"durability must be one of {DURABILITIES}, not {durability!r}")
129
+ if not isinstance(overwrite, bool):
130
+ raise TypeError("overwrite must be True or False")
131
+
132
+
133
+ def _publish(
134
+ path,
135
+ data,
136
+ *,
137
+ encoding: str | None,
138
+ errors: str | None,
139
+ newline: str | None,
140
+ mode: int | None,
141
+ overwrite: bool,
142
+ durability: str,
143
+ dir_fd: int | None,
144
+ follow_symlinks: bool,
145
+ ) -> int:
146
+ """Write `data` to a same-directory temporary file, then publish it.
147
+
148
+ `encoding is None` writes bytes; otherwise `data` is a str.
149
+ """
150
+ _check(durability, overwrite)
151
+ name = _resolve(path, dir_fd, follow_symlinks)
152
+ permissions = _permissions(mode, name, dir_fd)
153
+ directory = None if dir_fd is not None else os.path.dirname(os.path.abspath(name))
154
+ temporary = _temporary_name(name)
155
+ created = False
156
+ extra_kwargs = {} if dir_fd is None else {"src_dir_fd": dir_fd, "dst_dir_fd": dir_fd}
157
+ try:
158
+ descriptor = os.open(
159
+ temporary,
160
+ os.O_WRONLY | os.O_CREAT | os.O_EXCL,
161
+ 0o666 if permissions is None else permissions,
162
+ dir_fd=dir_fd,
163
+ )
164
+ created = True
165
+ open_kwargs = {} if encoding is None else {"encoding": encoding, "errors": errors, "newline": newline}
166
+ with os.fdopen(descriptor, "wb" if encoding is None else "w", **open_kwargs) as stream:
167
+ if permissions is not None:
168
+ os.fchmod(stream.fileno(), permissions)
169
+ written = stream.write(data)
170
+ stream.flush()
171
+ _sync_file(stream.fileno(), durability)
172
+ if overwrite:
173
+ os.replace(temporary, name, **extra_kwargs)
174
+ else:
175
+ os.link(temporary, name, follow_symlinks=False, **extra_kwargs)
176
+ os.unlink(temporary, dir_fd=dir_fd)
177
+ if durability in ("file+directory", "full"):
178
+ _sync_directory(directory, dir_fd)
179
+ return written
180
+ finally:
181
+ if created:
182
+ try:
183
+ os.unlink(temporary, dir_fd=dir_fd)
184
+ except FileNotFoundError:
185
+ pass
186
+
187
+
188
+ def write_text(
189
+ path,
190
+ text: str,
191
+ *,
192
+ encoding: str = "utf-8",
193
+ errors: str | None = None,
194
+ newline: str | None = None,
195
+ mode: int | str | None = None,
196
+ overwrite: bool = True,
197
+ durability: str = "file+directory",
198
+ dir_fd: int | None = None,
199
+ follow_symlinks: bool = True,
200
+ ) -> int:
201
+ """Publish `text` as `path`; return the number of characters written."""
202
+ if not isinstance(text, str):
203
+ raise TypeError("write_text expects str; use write_bytes for bytes")
204
+ return _publish(
205
+ path,
206
+ text,
207
+ encoding=encoding,
208
+ errors=errors,
209
+ newline=newline,
210
+ mode=mode,
211
+ overwrite=overwrite,
212
+ durability=durability,
213
+ dir_fd=dir_fd,
214
+ follow_symlinks=follow_symlinks,
215
+ )
216
+
217
+
218
+ def write_bytes(
219
+ path,
220
+ data,
221
+ *,
222
+ mode: int | str | None = None,
223
+ overwrite: bool = True,
224
+ durability: str = "file+directory",
225
+ dir_fd: int | None = None,
226
+ follow_symlinks: bool = True,
227
+ ) -> int:
228
+ """Publish bytes-like `data` as `path`; return the number of bytes written."""
229
+ if not isinstance(data, (bytes, bytearray, memoryview)):
230
+ raise TypeError("write_bytes expects bytes, bytearray or memoryview; use write_text for str")
231
+ return _publish(
232
+ path,
233
+ bytes(data),
234
+ encoding=None,
235
+ errors=None,
236
+ newline=None,
237
+ mode=mode,
238
+ overwrite=overwrite,
239
+ durability=durability,
240
+ dir_fd=dir_fd,
241
+ follow_symlinks=follow_symlinks,
242
+ )
243
+
244
+
245
+ def write_json(path, value: Any, **kwargs) -> int:
246
+ """Serialize `value` as JSON and publish it as `path`.
247
+
248
+ Serialization happens before the file is touched, so a value that cannot be
249
+ encoded leaves the destination untouched instead of publishing a fragment.
250
+
251
+ Accepted JSON keywords: `indent` (default 2), `sort_keys` (default False),
252
+ `ensure_ascii` (default False), `allow_nan` (default True), `separators`
253
+ (default None, the stdlib default), `default` (default None, as in
254
+ `json.dumps`), `newline` (default "\\n", None for none). Remaining
255
+ keywords go to `write_text`.
256
+ """
257
+ indent = kwargs.pop("indent", 2)
258
+ sort_keys = kwargs.pop("sort_keys", False)
259
+ ensure_ascii = kwargs.pop("ensure_ascii", False)
260
+ allow_nan = kwargs.pop("allow_nan", True)
261
+ separators = kwargs.pop("separators", None)
262
+ default = kwargs.pop("default", None)
263
+ newline = kwargs.pop("newline", "\n")
264
+ body = json.dumps(value, indent=indent, sort_keys=sort_keys, ensure_ascii=ensure_ascii,
265
+ allow_nan=allow_nan, separators=separators, default=default)
266
+ return write_text(path, body + (newline or ""), **kwargs)
267
+
268
+
269
+ class Staged:
270
+ """An open temporary file beside `path`, published only when asked.
271
+
272
+ `publish()` renames it over the destination; `discard()` removes it. The
273
+ context manager from `atomic_path` does one of the two for you.
274
+
275
+ `binary=True` gives a bytes stream (for chunked copies, zip files, uploads).
276
+ `path` is the temporary file's name (relative to `dir_fd` when one is
277
+ given). A caller that must check something before publishing (the staged
278
+ bytes, or that the destination is unchanged) calls `sync()`, checks, then
279
+ `publish()` or `discard()`; inside `atomic_path`, `discard()` also stops
280
+ the automatic publish.
281
+ """
282
+
283
+ def __init__(self, path, *, mode=None, overwrite=True, durability="file+directory",
284
+ dir_fd=None, encoding="utf-8", follow_symlinks=True, binary=False):
285
+ _check(durability, overwrite)
286
+ self._name = _resolve(path, dir_fd, follow_symlinks)
287
+ self._dir_fd = dir_fd
288
+ self._overwrite = overwrite
289
+ self._durability = durability
290
+ self._directory = None if dir_fd is not None else os.path.dirname(os.path.abspath(self._name))
291
+ self._temporary = _temporary_name(self._name)
292
+ self._finished = False
293
+ permissions = _permissions(mode, self._name, dir_fd)
294
+ descriptor = os.open(
295
+ self._temporary,
296
+ os.O_WRONLY | os.O_CREAT | os.O_EXCL,
297
+ 0o666 if permissions is None else permissions,
298
+ dir_fd=dir_fd,
299
+ )
300
+ try:
301
+ if permissions is not None:
302
+ os.fchmod(descriptor, permissions)
303
+ if binary:
304
+ self.stream: TextIO | BinaryIO = os.fdopen(descriptor, "wb")
305
+ else:
306
+ self.stream = os.fdopen(descriptor, "w", encoding=encoding, newline="")
307
+ except BaseException:
308
+ os.close(descriptor)
309
+ os.unlink(self._temporary, dir_fd=dir_fd)
310
+ raise
311
+
312
+ @property
313
+ def path(self) -> str:
314
+ """The temporary file, relative to `dir_fd` when one was given."""
315
+ return self._temporary
316
+
317
+ @property
318
+ def finished(self) -> bool:
319
+ return self._finished
320
+
321
+ def write(self, data) -> int:
322
+ return self.stream.write(data)
323
+
324
+ def fileno(self) -> int:
325
+ return self.stream.fileno()
326
+
327
+ def sync(self) -> None:
328
+ """Flush and fsync the staged bytes so they can be read back and checked."""
329
+ self.stream.flush()
330
+ _sync_file(self.stream.fileno(), self._durability)
331
+
332
+ def publish(self) -> None:
333
+ if self._finished:
334
+ raise RuntimeError("staged write is already finished")
335
+ self._finished = True
336
+ try:
337
+ self.sync()
338
+ self.stream.close()
339
+ extra_kwargs = {} if self._dir_fd is None else {"src_dir_fd": self._dir_fd, "dst_dir_fd": self._dir_fd}
340
+ if self._overwrite:
341
+ os.replace(self._temporary, self._name, **extra_kwargs)
342
+ else:
343
+ os.link(self._temporary, self._name, follow_symlinks=False, **extra_kwargs)
344
+ os.unlink(self._temporary, dir_fd=self._dir_fd)
345
+ if self._durability in ("file+directory", "full"):
346
+ _sync_directory(self._directory, self._dir_fd)
347
+ except BaseException:
348
+ self.discard()
349
+ raise
350
+
351
+ def discard(self) -> None:
352
+ self._finished = True
353
+ if not self.stream.closed:
354
+ self.stream.close()
355
+ try:
356
+ os.unlink(self._temporary, dir_fd=self._dir_fd)
357
+ except FileNotFoundError:
358
+ pass
359
+
360
+ def __enter__(self) -> "Staged":
361
+ return self
362
+
363
+ def __exit__(self, exc_type, exc, traceback) -> None:
364
+ if not self._finished:
365
+ self.discard()
366
+
367
+
368
+ @contextmanager
369
+ def atomic_path(path, **kwargs) -> Iterator[Staged]:
370
+ """Yield a `Staged` file; publish it when the block exits normally.
371
+
372
+ with atomic_path(target) as staged:
373
+ staged.write("{")
374
+ staged.write(body)
375
+ # `target` is replaced here.
376
+
377
+ An exception inside the block discards the temporary file and re-raises, so
378
+ the destination keeps its previous bytes.
379
+ """
380
+ staged = Staged(path, **kwargs)
381
+ try:
382
+ yield staged
383
+ except BaseException:
384
+ staged.discard()
385
+ raise
386
+ else:
387
+ if not staged.finished:
388
+ staged.publish()
@@ -0,0 +1,226 @@
1
+ Metadata-Version: 2.4
2
+ Name: feno-atomic-write
3
+ Version: 0.1.0
4
+ Summary: Replace a file with complete bytes, or leave the previous bytes in place.
5
+ License-Expression: MIT
6
+ Project-URL: Homepage, https://github.com/elfenomenokim/atomic-write
7
+ Project-URL: Repository, https://github.com/elfenomenokim/atomic-write
8
+ Project-URL: Issues, https://github.com/elfenomenokim/atomic-write/issues
9
+ Keywords: atomic,filesystem,durability,fsync,crash-safety
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3 :: Only
12
+ Classifier: Operating System :: POSIX
13
+ Classifier: Operating System :: MacOS
14
+ Classifier: Operating System :: Microsoft :: Windows
15
+ Classifier: Topic :: System :: Filesystems
16
+ Requires-Python: >=3.9
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Dynamic: license-file
20
+
21
+ # atomic-write
22
+
23
+ A Python library that replaces a file with complete bytes, or leaves the previous bytes in place.
24
+
25
+ Python 3.9+ · no dependencies
26
+
27
+ [한국어](README.ko.md) · [Install](#install) · [Quick start](#quick-start) · [Reference](#reference)
28
+
29
+ ```python
30
+ from atomic_write import write_json
31
+
32
+ write_json("state/quota.json", {"plan": "pro", "remaining": 42})
33
+ # Every reader sees the old file or the new one, never a partial write.
34
+ ```
35
+
36
+ <p align="center">
37
+ <picture>
38
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/atomic-write/main/docs/diagrams/write-path.dark.svg">
39
+ <img src="https://raw.githubusercontent.com/elfenomenokim/atomic-write/main/docs/diagrams/write-path.light.svg" width="640" alt="A write creates an exclusive temporary file beside the destination, sets its final mode, writes and fsyncs, then renames it onto the destination; a failure removes the temporary file and leaves the previous bytes.">
40
+ </picture>
41
+ </p>
42
+
43
+ ## Why
44
+
45
+ `os.replace` renames atomically, but it does not give you a temporary file, a
46
+ flush, an fsync, mode handling, create-only semantics, or a directory sync. Every
47
+ project that writes state ends up assembling those itself, and the assemblies
48
+ disagree: some chmod the temporary file after creating it, some never fsync the
49
+ directory, some use a temporary name qualified only by the process id.
50
+
51
+ The best-known dedicated library, [python-atomicwrites](https://github.com/untitaker/python-atomicwrites),
52
+ was archived in July 2022. Its `overwrite` flag gives race-free create-only
53
+ semantics; it does not document directory fsync or `dir_fd` control. This library
54
+ keeps those two contracts explicit and nothing else.
55
+
56
+ | | `os.replace` | python-atomicwrites | atomic-write |
57
+ |---|---|---|---|
58
+ | Same-directory temporary file | you build it | yes | yes |
59
+ | Directory fsync | no | not documented | `file+directory` (default) |
60
+ | Create-only that survives a race | no | `overwrite=False` | `overwrite=False` |
61
+ | Keeps the existing mode | no | not documented | default |
62
+ | `dir_fd` containment | you build it | no | `dir_fd=` |
63
+ | Maintained | stdlib | archived 2022 | this repository |
64
+
65
+ ## Install
66
+
67
+ ```sh
68
+ pip install feno-atomic-write
69
+ ```
70
+
71
+ The PyPI name is `feno-atomic-write` because `atomic-write` is too close to existing projects; the import name stays `atomic_write`.
72
+
73
+ Or install from a checkout:
74
+
75
+ ```sh
76
+ python3 -m pip install .
77
+ ```
78
+
79
+ ## Quick start
80
+
81
+ Replace a file and keep its permissions:
82
+
83
+ ```python
84
+ from atomic_write import write_text
85
+
86
+ write_text("~/.config/app/token", "abc123")
87
+ ```
88
+
89
+ Publish a claim that must not overwrite anyone else's:
90
+
91
+ ```python
92
+ from atomic_write import write_json
93
+ from pathlib import Path
94
+
95
+ write_json(Path("run/owner.json"), {"pid": 4242}, overwrite=False)
96
+ # FileExistsError when another process already claimed it.
97
+ ```
98
+
99
+ Write inside a directory you already validated:
100
+
101
+ ```python
102
+ import os
103
+ from atomic_write import write_bytes
104
+
105
+ directory = os.open(state_dir, os.O_RDONLY)
106
+ try:
107
+ write_bytes("cursor.bin", b"\x00\x01", dir_fd=directory)
108
+ finally:
109
+ os.close(directory)
110
+ ```
111
+
112
+ Skip the fsync where a lost file is acceptable, such as a cache:
113
+
114
+ ```python
115
+ from atomic_write import write_json
116
+
117
+ write_json("cache/quota.json", cache, durability="none")
118
+ ```
119
+
120
+ ## Reference
121
+
122
+ ### `write_text(path, text, *, encoding="utf-8", errors=None, newline=None, mode=None, overwrite=True, durability="file+directory", dir_fd=None, follow_symlinks=True) -> int`
123
+
124
+ Writes `text` and returns the number of characters written.
125
+
126
+ ### `write_bytes(path, data, *, mode=None, overwrite=True, durability="file+directory", dir_fd=None, follow_symlinks=True) -> int`
127
+
128
+ Accepts `bytes`, `bytearray` or `memoryview` and returns the number of bytes
129
+ written.
130
+
131
+ ### `write_json(path, value, **kwargs) -> int`
132
+
133
+ Serializes with `json.dumps` before touching the filesystem, so a value that
134
+ cannot be encoded leaves the destination untouched. Accepts `indent` (default 2),
135
+ `sort_keys` (default `False`), `ensure_ascii` (default `False`), `allow_nan`
136
+ (default `True`), `separators` (default the stdlib default), `default` (as in
137
+ `json.dumps`) and `newline` (default `"\n"`; `None` for none). Remaining keywords
138
+ go to `write_text`.
139
+
140
+ ### `atomic_path(path, **kwargs)`
141
+
142
+ Context manager yielding a `Staged` file, published when the block exits
143
+ normally and discarded when it raises:
144
+
145
+ ```python
146
+ from atomic_write import atomic_path
147
+
148
+ with atomic_path("report.md") as staged:
149
+ for row in rows:
150
+ staged.write(row + "\n")
151
+ # report.md is replaced here, only if the loop finished.
152
+ ```
153
+
154
+ `binary=True` gives a bytes stream for chunked copies, zip files or uploads.
155
+ `staged.path` names the temporary file and `staged.sync()` flushes and fsyncs it,
156
+ so a caller can check the staged bytes, or that the destination is unchanged,
157
+ before publishing. Calling `staged.discard()` inside the block skips the publish
158
+ and keeps the previous file:
159
+
160
+ ```python
161
+ import shutil, zipfile
162
+
163
+ with open(source, "rb") as src, atomic_path(target, binary=True, mode=0o600) as staged:
164
+ shutil.copyfileobj(src, staged)
165
+ staged.sync()
166
+ if not zipfile.is_zipfile(staged.path):
167
+ staged.discard() # target keeps its previous bytes
168
+ ```
169
+
170
+ ### Contracts
171
+
172
+ | Argument | Values | Meaning |
173
+ |---|---|---|
174
+ | `overwrite` | `True` (default) | Replace an existing file |
175
+ | | `False` | Publish a new file; `FileExistsError` if it exists. Uses `os.link`, so of two racing creators exactly one wins |
176
+ | `durability` | `none` | No fsync. A crash may lose the new file |
177
+ | | `file` | fsync the new bytes before the rename |
178
+ | | `file+directory` (default) | Also fsync the directory, so the rename survives a crash |
179
+ | | `full` | `file+directory`, plus macOS `F_FULLFSYNC` so the bytes reach stable media, not only the drive cache |
180
+ | `mode` | `int` or `None` | `None` keeps the existing file's permissions; a new file gets `0o666` minus the umask |
181
+ | | `"umask"` | Every write gets `0o666` minus the umask, ignoring the existing mode, like a plain `open(path, "w")` |
182
+ | `dir_fd` | `int` or `None` | Write relative to an open directory descriptor, using that same descriptor for the rename |
183
+ | `follow_symlinks` | `True` (default) | Replace the link's target and keep the link |
184
+ | | `False` | Replace the link itself |
185
+
186
+ A failed write never publishes partial bytes: the destination keeps its previous
187
+ contents and the temporary file is removed. Serialization happens before the file
188
+ is touched.
189
+
190
+ Two writers of the same path never share a temporary name, so a nested or
191
+ concurrent write cannot publish a file another writer is still filling. The
192
+ temporary file is always created beside the destination, whatever the process's
193
+ working directory (a launchd job runs with `/`).
194
+
195
+ A directory that cannot be fsynced (`EINVAL` or `ENOTSUP` on SMB or FUSE) is
196
+ skipped rather than raised, because the rename has already happened by then.
197
+
198
+ ## Platform notes
199
+
200
+ - Verified on macOS arm64 with CPython 3.12.
201
+ - On Windows, `follow_symlinks`, `dir_fd` and directory fsync are not exercised;
202
+ `os.replace` is atomic there, and the directory sync is skipped because Windows
203
+ has no directory fsync. **Not verified on Windows or Linux.**
204
+ - `dir_fd` is a containment tool, not a sandbox: a name containing `..` is still
205
+ resolved by the kernel. Validate names before passing them.
206
+
207
+ ## Limits
208
+
209
+ - It writes single files. It does not publish a directory tree, a manifest plus
210
+ its members, or a multi-file transaction.
211
+ - It does not lock. Callers that need a read-modify-write cycle own their own lock.
212
+ - It does not create parent directories. `FileNotFoundError` is raised instead.
213
+ - It does not verify the bytes it wrote by reading them back; `atomic_path` with
214
+ `staged.sync()` lets the caller do that before publishing.
215
+
216
+ ## Contributing
217
+
218
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Run the suite with:
219
+
220
+ ```sh
221
+ python3 -m pytest tests -q
222
+ ```
223
+
224
+ ## License
225
+
226
+ [MIT](LICENSE).
@@ -0,0 +1,6 @@
1
+ atomic_write/__init__.py,sha256=rucE2M_TDCdyBfTkK0s9Q11ppXq_U_54Sm1cb5zJhRY,13898
2
+ feno_atomic_write-0.1.0.dist-info/licenses/LICENSE,sha256=doJZh0OcqN6KH1mad-WIcL9Eovit4M2O3THyZB9_7gE,1068
3
+ feno_atomic_write-0.1.0.dist-info/METADATA,sha256=ZAUPdhAIcflWmXClupQhCEWhwa9_Lw1Epw_fVmnKoB0,8721
4
+ feno_atomic_write-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
5
+ feno_atomic_write-0.1.0.dist-info/top_level.txt,sha256=EuLPwH30-vKvVfU_b29TdsimPV0d2mDl5emZXAyRsGw,13
6
+ feno_atomic_write-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 El Fenomeno
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ atomic_write