atomic¶
Atomic writes of files and directories.
A file is written into a temporary file of its directory, which replaces it
once it is complete, so a reader sees the old or the new file and never a
partial one, and a file written twice, e.g. by a unit of a run which runs
again, keeps one complete content. The temporary file is created with the
mode 0o666 and the umask of the process, the mode of a file written with
open or Path.write_text, so a file written atomically is readable as any
other file of the directory. A directory is written the same way,
atomic_directory: a temporary directory next to it replaces it once it is
complete.
The module imports only the standard library.
Write a file atomically through a temporary path.
The caller writes the complete file to the yielded path, e.g. with
Path.write_text or xarray.Dataset.to_netcdf, which may replace the
empty file created there. On success the temporary file gets the mode of
a new file of the process, 0o666 without the bits of the umask, and
replaces path; on an exception it is removed and path is left as it
was.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
Path
|
the file to write; its directory must exist. |
required |
Yields:
| Type | Description |
|---|---|
Generator[Path]
|
The temporary path in the directory of |
Write a text file atomically in utf-8, see atomic_path.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
Path
|
the file to write; its directory must exist. |
required |
text
|
str
|
the content of the file. |
required |
Write a directory atomically through a temporary directory.
The caller writes the complete directory into the yielded one, which
replaces path on success: an existing path is moved aside first and
removed after the new one took its place (best effort: a directory which
is not removed is logged and left next to it). On an exception the
temporary directory is removed and path is left as it was, also when
the new directory fails to take its place after the old one was moved.
The directory is created with the mode 0o777 and the umask of the
process, as a directory created with mkdir.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
Path
|
the directory to write; its parent must exist. |
required |
Yields:
| Type | Description |
|---|---|
Generator[Path]
|
The temporary directory next to |
Raises:
| Type | Description |
|---|---|
FileExistsError
|
if no free name was found. |