Async operator

The entry class for all public async APIs.

Parameters:

Name	Type	Description	Default
scheme	str	The service name that OpenDAL supports.	required
**options	any	The options for the service. See the documentation of each service for more details.	{}

Example

import opendal

op = opendal.AsyncOperator("s3", bucket="bucket", region="us-east-1")
await op.write("hello.txt", b"hello world")

copy(source, target) async

Copy the object from source to target.

Parameters:

Name	Type	Description	Default
source	str | Path	The source path.	required
target	str | Path	The target path.	required

create_dir(path) async

Create a directory at the given path.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the directory.	required

delete(path) async

Delete the object at the given path.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the object.	required

exists(path) async

Check if the object at the given path exists.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the object.	required

Returns

True if the object exists, False otherwise.

list(path, **kwargs) async

List objects at the given path.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the directory/ prefix.	required
**kwargs	Any	Optional listing parameters matching the OpenDAL ListOptions: limit (int): The limit passed to the underlying service to specify the max results that could return per-request. Users could use this to control the memory usage of list operation. If not set, all matching entries will be listed. start_after (str): Start listing after this key. Useful for pagination or resuming interrupted listings. recursive (bool): Whether to list entries recursively through all subdirectories. If False, lists only top-level entries (entries under the given path). versions (bool): Whether to include all versions of objects, if the underlying service supports versioning. deleted (bool): Whether to include deleted objects, if the underlying service supports soft-deletes or versioning.	{}

Returns

Iterable[Entry]: An iterable of entries representing the objects in the
    directory or prefix.

open(path, mode, **options) async

Open a file at the given path for reading or writing.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the file.	required
mode	str	The mode to open the file. Must be either "rb" for reading or "wb" for writing.	required
**options	Any	Additional options passed to the underlying OpenDAL reader or writer. - If mode == "rb": options match the OpenDAL ReaderOptions. - If mode == "wb": options match the OpenDAL WriteOptions.	{}

Returns

AsyncFile: A file-like object that can be used to read or write the file.

Example

import opendal

op = opendal.AsyncOperator("s3", bucket="bucket", region="us-east-1")
async with await op.open("hello.txt", "wb") as f:
    await f.write(b"hello world")

presign_delete(path, expire_second) async

Generate a presigned URL for delete operation.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the object.	required
expire_second	int	The expiration time in seconds.	required

Returns

A presigned request object.

presign_read(path, expire_second) async

Generate a presigned URL for read operation.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the object.	required
expire_second	int	The expiration time in seconds.	required

Returns

A presigned request object.

presign_stat(path, expire_second) async

Generate a presigned URL for stat operation.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the object.	required
expire_second	int	The expiration time in seconds.	required

Returns

A presigned request object.

presign_write(path, expire_second) async

Generate a presigned URL for write operation.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the object.	required
expire_second	int	The expiration time in seconds.	required

Returns

A presigned request object.

read(path, **options) async

Read the content of the object at the given path.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the object.	required
**options	Any	Optional read parameters matching the OpenDAL ReadOptions: offset (int): Byte offset to start reading from. Defaults to 0 if not specified. size (int): Number of bytes to read. If not specified, reads until the end of the object. Together, offset and size define the byte range for reading. version (str): Specify the version of the object to read, if supported by the backend. concurrent (int): Level of concurrency for reading. Defaults to backend-specific value. chunk (int): Read chunk size in bytes. gap (int): Minimum gap (in bytes) between chunks to consider them separate. override_content_type (str): Override the returned content type. if_match (str): Read only if the ETag matches the given value. if_none_match (str): Read-only if the ETag does not match the given value. if_modified_since (datetime): Only read if the object was modified since this timestamp. This timestamp must be in UTC. if_unmodified_since (datetime): Only read if the object was not modified since this timestamp. This timestamp must be in UTC.	{}

Returns

The content of the object as bytes.

remove_all(path) async

Remove all objects at the given path.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the directory.	required

rename(source, target) async

Rename the object from source to target.

Parameters:

Name	Type	Description	Default
source	str | Path	The source path.	required
target	str | Path	The target path.	required

scan(path, **kwargs) async

Scan the objects at the given path recursively.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the directory/ prefix.	required
**kwargs	Any	Optional listing parameters matching the OpenDAL ListOptions, excluding recursive which is always enforced as True	{}

Returns

Iterable[Entry]: An iterable of all entries under the given path,
    recursively traversing all subdirectories. Each entry represents
    an object (e.g., file or directory) discovered within the full
    descendant hierarchy of the specified path.

stat(path, **kwargs) async

Get the metadata of the object at the given path.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the object.	required
**kwargs	Any	Optional stat parameters matching the OpenDAL StatOptions: version (str): Specify the version of the object to read, if supported by the backend. if_match (str): Read only if the ETag matches the given value. if_none_match (str): Read-only if the ETag does not match the given value. if_modified_since (datetime): Only read if the object was modified since this timestamp. This timestamp must be in UTC. if_unmodified_since (datetime): Only read if the object was not modified since this timestamp. This timestamp must be in UTC. cache_control (str): Override the cache-control header for the object. content_type (str): Explicitly set the Content-Type header for the object. content_disposition (str): Sets how the object should be presented (e.g., as an attachment).	{}

Returns

Metadata: The metadata of the object.

write(path, bs, **options) async

Write the content to the object at the given path.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the object.	required
bs	bytes	The content to write.	required
**options	Any	Optional write parameters matching the OpenDAL WriteOptions: append (bool): If True, append to the object instead of overwriting. chunk (int): Specify the chunk size in bytes for multipart uploads. concurrent (int): Number of concurrent upload parts. Larger values can improve performance. cache_control (str): Override the cache-control header for the object. content_type (str): Explicitly set the Content-Type header for the object. content_disposition (str): Sets how the object should be presented (e.g., as an attachment). content_encoding (str): Override the Content-Encoding header. if_match (str): Perform the write only if the object's current ETag matches the given one. if_none_match (str): Perform the write only if the object's current ETag does NOT match the given one. if_not_exists (bool): Only write the object if it doesn't already exist. user_metadata (dict[str, str]): Custom user metadata to associate with the object.	{}

Returns

None