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.
atomic_write/__init__.py
ADDED
|
@@ -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,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
|