API Reference

AtomicWriter

AtomicWriter(
    destination: StrPath, *, overwrite: bool = False
)

Create and manage a file for atomic writes.

Changes are staged in a temporary file within the destination file's directory, then atomically moved to the destination file on commit.

Parameters:

Name	Type	Description	Default
`destination`	`StrPath`	The path to the destination file.	required
`overwrite`	`bool`	Whether to overwrite the destination file if it already exists.	`False`

Raises:

Type	Description
`OSError`	If any OS-level error occurs during temporary file creation.

destination: Path

The absolute path to the destination file.

overwrite: bool

Whether to overwrite the destination file if it already exists.

write_bytes(data: bytes) -> None

Write bytes to the temporary file.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	The bytes to write.	required

Raises:

Type	Description
`ValueError`	If attempting to write to a file that has already been committed and closed.
`OSError`	If an OS-level error occurs during write.

write_text(data: str) -> None

Write text to the temporary file.

Parameters:

Name	Type	Description	Default
`data`	`str`	The text to write.	required

Raises:

Type	Description
`ValueError`	If attempting to write to a file that has already been committed and closed.
`OSError`	If an OS-level error occurs during write.

commit() -> None

Commit the contents of the temporary file to the destination file.

This method atomically moves the temporary file to the destination file. It's also idempotent and can be called multiple times without error.

Raises:

Type	Description
`FileExistsError`	If `overwrite` is `False` and the destination file already exists.
`OSError`	If an OS-level error occurs during file persistence or sync.