API Reference

Note

This library will only ever raise the errors explicitly documented for each method. If you encounter any other error, please consider it a bug and report it.

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 property

destination: Path

The absolute path to the destination file.

overwrite property

overwrite: bool

Whether to overwrite the destination file if it already exists.

write_bytes

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

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

commit() -> None

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

This method atomically moves the temporary file to the destination file.

Raises:

Type	Description
FileExistsError	If overwrite is False and the destination file already exists.
ValueError	If attempting to commit a file that has already been committed and closed.
OSError	If an OS-level error occurs during file persistence or sync.