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.
@@ -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"]