Filesystem utilities reference¶

temp_directory ¶

temp_directory() -> Generator[Path, None, None]

A context manager that creates a temporary directory and yields a path to it. Example:

with temp_directory() as td:
    ...

Yields:

Type	Description
`Path`	The resolved path to the temporary directory, following all symlinks.

temp_file ¶

temp_file(suffix: str = '') -> Generator[Path, None, None]

A context manager that creates a temporary file and yields a path to it. Example:

with temp_file() as tf:
    ...

Yields:

Type	Description
`Path`	The resolved path to the temporary file, following all symlinks.

Path ¶

Bases: Path

long_id ¶

long_id: str

Returns a SHA-256 hashed, URL-safe base64 encoded representation of the current path. This is useful on case-insensitive filesystems to identify paths that are the same.

Caveat

This identifier considers the filesystem to be case-insensitive on macOS. Although that is not a technical guarantee, it is in practice true.

Returns:

Type	Description
`str`	A unique identifier for the current path.

id ¶

id: str

Returns:

Type	Description
`str`	The first 8 characters of the long ID.

ensure_dir ¶

ensure_dir() -> None

Ensure the current path is a directory. Equivalent to calling Path.mkdir with parents=True and exist_ok=True.

expand ¶

expand() -> Path

Expand the current path by resolving the user home directory and environment variables.

Returns:

Type	Description
`Path`	The new expanded path.

write_atomic ¶

write_atomic(data: str | bytes, *args: Any, **kwargs: Any) -> None

Atomically write data to the current path. This is equivalent to the following:

with path.open_atomic("w", encoding="utf-8") as f:
    f.write(data)

Parameters:

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

Other Parameters:

Name	Type	Description
`*args`	`Any`	Additional arguments to pass to `os.fdopen`.
`**kwargs`	`Any`	Additional keyword arguments to pass to `os.fdopen`.

open_atomic ¶

open_atomic(
    *args: Any, **kwargs: Any
) -> Generator[IO[Any], None, None]

Atomically open a file for writing.

Other Parameters:

Name	Type	Description
`*args`	`Any`	Additional arguments to pass to `os.fdopen`.
`**kwargs`	`Any`	Additional keyword arguments to pass to `os.fdopen`.

as_cwd ¶

as_cwd() -> Generator[Path, None, None]

A context manager that changes the current working directory to the current path. Example:

with Path("foo").as_cwd():
    ...

Yields:

Type	Description
`Path`	The current path.

as_exe ¶

as_exe() -> Path

Return the current path with the appropriate executable suffix.

hexdigest ¶

hexdigest(
    *, algorithm: str = "sha256", buffer_size: int | None = None
) -> str

Returns a hexadecimal string representation of the file's digest. The algorithm used can be any algorithm supported by hashlib, as defined in hashlib. Defaults to sha256. Will raise FileNotFoundError if the path does not exist, and OSError if it is not a file.

Parameters:

Name	Type	Description	Default
`algorithm`	`str`	The hashing algorithm to use to calculate the digest, specified as a string. Must be a member of hashlib.algorithms_guaranteed.	`'sha256'`
`buffer_size`	`int \| None`	The size, in bytes, of the in-memory buffer to use for reading the file while hashing. Defaults to None, which lets hashlib choose the buffer size.	`None`