Skip to content

bagof.paths.AsyncPath 

AsyncPath(path: Any, *, driver: Any = None, storage_options: Mapping[str, Any] | None = None)

Bases: PurePathMixin, LocalCopyMixin, BaseWrapper

The await version of Path: the same methods, as coroutines.

The parts that only describe a path (name, parent, /) stay plain; the parts that touch storage are awaited.

>>> import asyncio
>>> from bagof.paths import AsyncPath
>>> async def main() -> None:
...     p = AsyncPath("/etc/hostname")
...     if await p.exists():
...         print(await p.read_text())

Methods:

exists async 

exists(*, follow_symlinks: bool = True) -> bool

Whether the path exists.

On a local path this follows Python 3.14 on every version: an error returns False rather than raising. A name too long for the file system is not there, and neither is one whose parent you may not search. To see the error, call stat(), which still raises. The other status checks (is_file, is_dir, is_symlink, ...) do the same.

follow_symlinks=False (also on is_file and is_dir) asks about a symbolic link itself, on every Python version.

>>> import asyncio
>>> asyncio.run(AsyncPath("a" * 300).exists())
False

is_file async 

is_file(*, follow_symlinks: bool = True) -> bool

Whether the path is a regular file.

Like exists, it returns False on an error on a local path.

is_dir async 

is_dir(*, follow_symlinks: bool = True) -> bool

Whether the path is a directory.

Like exists, it returns False on an error on a local path.

is_symlink() -> bool

Whether the path is a symbolic link.

stat async 

stat(*, follow_symlinks: bool = True) -> stat_result

The result of stat on the path.

lstat async 

lstat() -> stat_result

Like stat, without following symbolic links.

samefile async 

samefile(other: Any, *, strict: bool = True) -> bool

Whether the path and other refer to the same file.

strict=False works as in Path.samefile.

is_mount async 

is_mount() -> bool

Whether the path is a mount point.

is_socket async 

is_socket() -> bool

Whether the path is a Unix domain socket.

is_fifo async 

is_fifo() -> bool

Whether the path is a FIFO (named pipe).

is_block_device async 

is_block_device() -> bool

Whether the path is a block device.

is_char_device async 

is_char_device() -> bool

Whether the path is a character device.

is_junction async 

is_junction() -> bool

Whether the path is a junction (a Windows concept; else False).

open async 

open(mode: str = 'r', buffering: int = -1, encoding: str | None = None, errors: str | None = None, newline: str | None = None, *, atomic: bool = False) -> Any

Open the path and return an async file object.

Use it with async with / async for. The handle's reads and writes are awaited directly on a native driver, or run in a worker thread on a synchronous one. atomic=True works as in Path.open: closing commits, leaving an async with block with an error discards.

read_bytes async 

read_bytes() -> bytes

Read the whole file as bytes.

read_text async 

read_text(encoding: str | None = None, errors: str | None = None, newline: str | None = None) -> str

Read the whole file as text.

write_bytes async 

write_bytes(data: Any, *, atomic: bool = False) -> int

Write data to the file as bytes, replacing any content.

atomic=True works as in Path.write_bytes.

write_text async 

write_text(data: str, encoding: str | None = None, errors: str | None = None, newline: str | None = None, *, atomic: bool = False) -> int

Write data to the file as text, replacing any content.

atomic=True works as in Path.write_bytes.

staged 

staged(*, copy: bool = False, replace_type: bool = False, keep_on_failure: bool = False) -> AsyncStage

A staging area for a new version of this path.

The same as Path.staged, used with async with; the staged path is an AsyncPath:

async with AsyncPath("out/scan.nii.gz").staged() as tmp:
    await tmp.write_bytes(content)

Outside an async with block, await it to make the staging area, then await its commit() or discard().

iterdir async 

iterdir() -> AsyncIterator[Self]

Yield the paths of the directory's entries.

glob async 

glob(pattern: str, *, case_sensitive: bool | None = None, recurse_symlinks: bool = False) -> AsyncIterator[Self]

Yield the paths matching pattern under this directory.

rglob async 

rglob(pattern: str, *, case_sensitive: bool | None = None, recurse_symlinks: bool = False) -> AsyncIterator[Self]

Like glob, recursively.

mkdir async 

mkdir(mode: int = 511, parents: bool = False, exist_ok: bool = False) -> None

Create a directory at the path.

touch async 

touch(mode: int = 438, exist_ok: bool = True) -> None

Create the file at the path, or update its modification time.

unlink(*, missing_ok: bool = False) -> None

Remove the file at the path.

rmdir async 

rmdir(*, recursive: bool = False) -> None

Remove the directory at the path.

copy async 

copy(target: Any, *, follow_symlinks: bool = True, preserve_metadata: bool = False) -> Self

Copy this file or directory to target; return the new path.

copy_into async 

copy_into(target_dir: Any, *, follow_symlinks: bool = True, preserve_metadata: bool = False) -> Self

Copy into target_dir, keeping this path's name.

move async 

move(target: Any) -> Self

Move this path to target; return the new path.

move_into async 

move_into(target_dir: Any) -> Self

Move into target_dir, keeping this path's name.

walk async 

walk(top_down: bool = True, on_error: Callable | None = None, follow_symlinks: bool = False) -> AsyncIterator[tuple[Self, list[str], list[str]]]

Walk the tree, yielding (path, dirnames, filenames) per dir.

One directory per thread hop, so mutating dirnames in place to prune the descent works exactly as it does on the sync wrapper. Note that on_error runs in a worker thread.

A natively-async driver walks on its own coroutine surface; pruning by editing dirnames is not propagated there, since the driver produced the whole level before it was yielded.

resolve async 

resolve(strict: bool = False) -> Self

The absolute path, with symlinks resolved.

absolute async 

absolute() -> Self

The absolute path, without resolving symlinks.

expanduser async 

expanduser() -> Self

The path with a leading ~ expanded.

readlink() -> Self

The path a symbolic link points to.

rename async 

rename(target: Any) -> Self

Rename the path to target and return the new path.

replace async 

replace(target: Any) -> Self

Rename the path to target, replacing any existing file.

chmod async 

chmod(mode: int, *, follow_symlinks: bool = True) -> None

Change the file mode and permission bits.

lchmod async 

lchmod(mode: int) -> None

Like chmod, without following symbolic links.

owner async 

owner(*, follow_symlinks: bool = True) -> str

The login name of the file's owner.

group async 

group(*, follow_symlinks: bool = True) -> str

The group name of the file.

symlink_to(target: Any, target_is_directory: bool = False) -> None

Make this path a symbolic link to target.

hardlink_to(target: Any) -> None

Make this path a hard link to target.

link_to(target: Any) -> None

Make target a hard link to this path.

.. deprecated:: link_to takes the reverse argument order of hardlink_to and was removed from pathlib in Python 3.12. Prefer hardlink_to; this is kept, and synthesized where the driver dropped it, only for backward compatibility.

as_url async 

as_url(**kwargs: Any) -> str

A URL for the path; keyword arguments pass to the driver.

download_to async 

download_to(destination: Any) -> Any

Download the path's contents to a local destination.

upload_from async 

upload_from(source: Any, **kwargs: Any) -> Any

Upload a local source to the path.

clear_cache async 

clear_cache() -> None

Discard any locally cached copy of the path (cloudpathlib).

rmtree async 

rmtree() -> None

Remove the directory tree at the path. Alias of rmdir.

copytree async 

copytree(target: Any, *, follow_symlinks: bool = True, preserve_metadata: bool = False) -> Self

Copy a directory tree to target. Alias of copy.

bagof.paths.AsyncStage 

AsyncStage(target: Any, *, copy: bool = False, replace_type: bool = False, keep_on_failure: bool = False)

Bases: _StageBase

The asynchronous staging area returned by AsyncPath.staged.

Use it with async with, or await it to prepare it and then await its commit or discard. The staging directory is made when it is entered or awaited.

Attributes

path property 

path: Any

Where to create the new version: named like the target.

Available once the stage is entered or awaited.

Methods:

commit async 

commit() -> None

Move what was created at path onto the target.

The same rules as Stage.commit.

discard async 

discard() -> None

Remove the staged version; the target is never touched.