feno-atomic-write 0.1.0__tar.gz
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.
- feno_atomic_write-0.1.0/LICENSE +21 -0
- feno_atomic_write-0.1.0/PKG-INFO +226 -0
- feno_atomic_write-0.1.0/README.md +206 -0
- feno_atomic_write-0.1.0/pyproject.toml +30 -0
- feno_atomic_write-0.1.0/python/atomic_write/__init__.py +388 -0
- feno_atomic_write-0.1.0/python/feno_atomic_write.egg-info/PKG-INFO +226 -0
- feno_atomic_write-0.1.0/python/feno_atomic_write.egg-info/SOURCES.txt +9 -0
- feno_atomic_write-0.1.0/python/feno_atomic_write.egg-info/dependency_links.txt +1 -0
- feno_atomic_write-0.1.0/python/feno_atomic_write.egg-info/top_level.txt +1 -0
- feno_atomic_write-0.1.0/setup.cfg +4 -0
- feno_atomic_write-0.1.0/tests/test_atomic_write.py +544 -0
|
@@ -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,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,206 @@
|
|
|
1
|
+
# atomic-write
|
|
2
|
+
|
|
3
|
+
A Python library that replaces a file with complete bytes, or leaves the previous bytes in place.
|
|
4
|
+
|
|
5
|
+
Python 3.9+ · no dependencies
|
|
6
|
+
|
|
7
|
+
[한국어](README.ko.md) · [Install](#install) · [Quick start](#quick-start) · [Reference](#reference)
|
|
8
|
+
|
|
9
|
+
```python
|
|
10
|
+
from atomic_write import write_json
|
|
11
|
+
|
|
12
|
+
write_json("state/quota.json", {"plan": "pro", "remaining": 42})
|
|
13
|
+
# Every reader sees the old file or the new one, never a partial write.
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
<p align="center">
|
|
17
|
+
<picture>
|
|
18
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/atomic-write/main/docs/diagrams/write-path.dark.svg">
|
|
19
|
+
<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.">
|
|
20
|
+
</picture>
|
|
21
|
+
</p>
|
|
22
|
+
|
|
23
|
+
## Why
|
|
24
|
+
|
|
25
|
+
`os.replace` renames atomically, but it does not give you a temporary file, a
|
|
26
|
+
flush, an fsync, mode handling, create-only semantics, or a directory sync. Every
|
|
27
|
+
project that writes state ends up assembling those itself, and the assemblies
|
|
28
|
+
disagree: some chmod the temporary file after creating it, some never fsync the
|
|
29
|
+
directory, some use a temporary name qualified only by the process id.
|
|
30
|
+
|
|
31
|
+
The best-known dedicated library, [python-atomicwrites](https://github.com/untitaker/python-atomicwrites),
|
|
32
|
+
was archived in July 2022. Its `overwrite` flag gives race-free create-only
|
|
33
|
+
semantics; it does not document directory fsync or `dir_fd` control. This library
|
|
34
|
+
keeps those two contracts explicit and nothing else.
|
|
35
|
+
|
|
36
|
+
| | `os.replace` | python-atomicwrites | atomic-write |
|
|
37
|
+
|---|---|---|---|
|
|
38
|
+
| Same-directory temporary file | you build it | yes | yes |
|
|
39
|
+
| Directory fsync | no | not documented | `file+directory` (default) |
|
|
40
|
+
| Create-only that survives a race | no | `overwrite=False` | `overwrite=False` |
|
|
41
|
+
| Keeps the existing mode | no | not documented | default |
|
|
42
|
+
| `dir_fd` containment | you build it | no | `dir_fd=` |
|
|
43
|
+
| Maintained | stdlib | archived 2022 | this repository |
|
|
44
|
+
|
|
45
|
+
## Install
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
pip install feno-atomic-write
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The PyPI name is `feno-atomic-write` because `atomic-write` is too close to existing projects; the import name stays `atomic_write`.
|
|
52
|
+
|
|
53
|
+
Or install from a checkout:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
python3 -m pip install .
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Quick start
|
|
60
|
+
|
|
61
|
+
Replace a file and keep its permissions:
|
|
62
|
+
|
|
63
|
+
```python
|
|
64
|
+
from atomic_write import write_text
|
|
65
|
+
|
|
66
|
+
write_text("~/.config/app/token", "abc123")
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Publish a claim that must not overwrite anyone else's:
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
from atomic_write import write_json
|
|
73
|
+
from pathlib import Path
|
|
74
|
+
|
|
75
|
+
write_json(Path("run/owner.json"), {"pid": 4242}, overwrite=False)
|
|
76
|
+
# FileExistsError when another process already claimed it.
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Write inside a directory you already validated:
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
import os
|
|
83
|
+
from atomic_write import write_bytes
|
|
84
|
+
|
|
85
|
+
directory = os.open(state_dir, os.O_RDONLY)
|
|
86
|
+
try:
|
|
87
|
+
write_bytes("cursor.bin", b"\x00\x01", dir_fd=directory)
|
|
88
|
+
finally:
|
|
89
|
+
os.close(directory)
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Skip the fsync where a lost file is acceptable, such as a cache:
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
from atomic_write import write_json
|
|
96
|
+
|
|
97
|
+
write_json("cache/quota.json", cache, durability="none")
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Reference
|
|
101
|
+
|
|
102
|
+
### `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`
|
|
103
|
+
|
|
104
|
+
Writes `text` and returns the number of characters written.
|
|
105
|
+
|
|
106
|
+
### `write_bytes(path, data, *, mode=None, overwrite=True, durability="file+directory", dir_fd=None, follow_symlinks=True) -> int`
|
|
107
|
+
|
|
108
|
+
Accepts `bytes`, `bytearray` or `memoryview` and returns the number of bytes
|
|
109
|
+
written.
|
|
110
|
+
|
|
111
|
+
### `write_json(path, value, **kwargs) -> int`
|
|
112
|
+
|
|
113
|
+
Serializes with `json.dumps` before touching the filesystem, so a value that
|
|
114
|
+
cannot be encoded leaves the destination untouched. Accepts `indent` (default 2),
|
|
115
|
+
`sort_keys` (default `False`), `ensure_ascii` (default `False`), `allow_nan`
|
|
116
|
+
(default `True`), `separators` (default the stdlib default), `default` (as in
|
|
117
|
+
`json.dumps`) and `newline` (default `"\n"`; `None` for none). Remaining keywords
|
|
118
|
+
go to `write_text`.
|
|
119
|
+
|
|
120
|
+
### `atomic_path(path, **kwargs)`
|
|
121
|
+
|
|
122
|
+
Context manager yielding a `Staged` file, published when the block exits
|
|
123
|
+
normally and discarded when it raises:
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
from atomic_write import atomic_path
|
|
127
|
+
|
|
128
|
+
with atomic_path("report.md") as staged:
|
|
129
|
+
for row in rows:
|
|
130
|
+
staged.write(row + "\n")
|
|
131
|
+
# report.md is replaced here, only if the loop finished.
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
`binary=True` gives a bytes stream for chunked copies, zip files or uploads.
|
|
135
|
+
`staged.path` names the temporary file and `staged.sync()` flushes and fsyncs it,
|
|
136
|
+
so a caller can check the staged bytes, or that the destination is unchanged,
|
|
137
|
+
before publishing. Calling `staged.discard()` inside the block skips the publish
|
|
138
|
+
and keeps the previous file:
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
import shutil, zipfile
|
|
142
|
+
|
|
143
|
+
with open(source, "rb") as src, atomic_path(target, binary=True, mode=0o600) as staged:
|
|
144
|
+
shutil.copyfileobj(src, staged)
|
|
145
|
+
staged.sync()
|
|
146
|
+
if not zipfile.is_zipfile(staged.path):
|
|
147
|
+
staged.discard() # target keeps its previous bytes
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### Contracts
|
|
151
|
+
|
|
152
|
+
| Argument | Values | Meaning |
|
|
153
|
+
|---|---|---|
|
|
154
|
+
| `overwrite` | `True` (default) | Replace an existing file |
|
|
155
|
+
| | `False` | Publish a new file; `FileExistsError` if it exists. Uses `os.link`, so of two racing creators exactly one wins |
|
|
156
|
+
| `durability` | `none` | No fsync. A crash may lose the new file |
|
|
157
|
+
| | `file` | fsync the new bytes before the rename |
|
|
158
|
+
| | `file+directory` (default) | Also fsync the directory, so the rename survives a crash |
|
|
159
|
+
| | `full` | `file+directory`, plus macOS `F_FULLFSYNC` so the bytes reach stable media, not only the drive cache |
|
|
160
|
+
| `mode` | `int` or `None` | `None` keeps the existing file's permissions; a new file gets `0o666` minus the umask |
|
|
161
|
+
| | `"umask"` | Every write gets `0o666` minus the umask, ignoring the existing mode, like a plain `open(path, "w")` |
|
|
162
|
+
| `dir_fd` | `int` or `None` | Write relative to an open directory descriptor, using that same descriptor for the rename |
|
|
163
|
+
| `follow_symlinks` | `True` (default) | Replace the link's target and keep the link |
|
|
164
|
+
| | `False` | Replace the link itself |
|
|
165
|
+
|
|
166
|
+
A failed write never publishes partial bytes: the destination keeps its previous
|
|
167
|
+
contents and the temporary file is removed. Serialization happens before the file
|
|
168
|
+
is touched.
|
|
169
|
+
|
|
170
|
+
Two writers of the same path never share a temporary name, so a nested or
|
|
171
|
+
concurrent write cannot publish a file another writer is still filling. The
|
|
172
|
+
temporary file is always created beside the destination, whatever the process's
|
|
173
|
+
working directory (a launchd job runs with `/`).
|
|
174
|
+
|
|
175
|
+
A directory that cannot be fsynced (`EINVAL` or `ENOTSUP` on SMB or FUSE) is
|
|
176
|
+
skipped rather than raised, because the rename has already happened by then.
|
|
177
|
+
|
|
178
|
+
## Platform notes
|
|
179
|
+
|
|
180
|
+
- Verified on macOS arm64 with CPython 3.12.
|
|
181
|
+
- On Windows, `follow_symlinks`, `dir_fd` and directory fsync are not exercised;
|
|
182
|
+
`os.replace` is atomic there, and the directory sync is skipped because Windows
|
|
183
|
+
has no directory fsync. **Not verified on Windows or Linux.**
|
|
184
|
+
- `dir_fd` is a containment tool, not a sandbox: a name containing `..` is still
|
|
185
|
+
resolved by the kernel. Validate names before passing them.
|
|
186
|
+
|
|
187
|
+
## Limits
|
|
188
|
+
|
|
189
|
+
- It writes single files. It does not publish a directory tree, a manifest plus
|
|
190
|
+
its members, or a multi-file transaction.
|
|
191
|
+
- It does not lock. Callers that need a read-modify-write cycle own their own lock.
|
|
192
|
+
- It does not create parent directories. `FileNotFoundError` is raised instead.
|
|
193
|
+
- It does not verify the bytes it wrote by reading them back; `atomic_path` with
|
|
194
|
+
`staged.sync()` lets the caller do that before publishing.
|
|
195
|
+
|
|
196
|
+
## Contributing
|
|
197
|
+
|
|
198
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md). Run the suite with:
|
|
199
|
+
|
|
200
|
+
```sh
|
|
201
|
+
python3 -m pytest tests -q
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
## License
|
|
205
|
+
|
|
206
|
+
[MIT](LICENSE).
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "feno-atomic-write"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Replace a file with complete bytes, or leave the previous bytes in place."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
keywords = ["atomic", "filesystem", "durability", "fsync", "crash-safety"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Programming Language :: Python :: 3",
|
|
16
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
17
|
+
"Operating System :: POSIX",
|
|
18
|
+
"Operating System :: MacOS",
|
|
19
|
+
"Operating System :: Microsoft :: Windows",
|
|
20
|
+
"Topic :: System :: Filesystems",
|
|
21
|
+
]
|
|
22
|
+
|
|
23
|
+
[project.urls]
|
|
24
|
+
Homepage = "https://github.com/elfenomenokim/atomic-write"
|
|
25
|
+
Repository = "https://github.com/elfenomenokim/atomic-write"
|
|
26
|
+
Issues = "https://github.com/elfenomenokim/atomic-write/issues"
|
|
27
|
+
|
|
28
|
+
[tool.setuptools]
|
|
29
|
+
package-dir = { "" = "python" }
|
|
30
|
+
packages = ["atomic_write"]
|