Async operator

The async equivalent of Operator.

AsyncOperator is the entry point for all async APIs.

`new(scheme, **kwargs)` #

Create a new AsyncOperator.

Parameters:

Name	Type	Description	Default
`scheme`	`str \| Scheme`	The scheme of the service.	required
`**kwargs`	`dict`	The options for the service. Path-like values are converted to strings.	`{}`

Returns:

Type	Description
`AsyncOperator`	The new async operator.

`capability()` #

Get all capabilities of this operator.

Returns:

Type	Description
`Capability`	The capability of the operator.

`check()` #

Check if the operator is able to work correctly.

Returns:

Type	Description
`coroutine`	An awaitable that completes when the check is finished.

Raises:

Type	Description
`Exception`	If the operator is not able to work correctly.

`copy(source, target)` #

Copy a file from one path to another.

Parameters:

Name	Type	Description	Default
`source`	`str`	The path to the source file.	required
`target`	`str`	The path to the target file.	required

Returns:

Type	Description
`coroutine`	An awaitable that completes when the copy is finished.

`create_dir(path)` #

Create a directory at the given path.

Notes

To indicate that a path is a directory, it must end with a /. This operation is always recursive, like mkdir -p.

Parameters:

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

Returns:

Type	Description
`coroutine`	An awaitable that completes when the directory is created.

`delete(path, *, version=None, recursive=None, if_match=None)` #

Delete a file at the given path.

Notes

This operation will not return an error if the path does not exist.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path to the file.	required

Returns:

Name	Type	Description
	`coroutine`	An awaitable that completes when the file is deleted.
`version`	`(str, optional)`	The version of the file to delete. Only supported on version-aware backends.
`recursive`	`(bool, optional)`	If True, delete the path recursively. Only supported on backends that support recursive delete.
`if_match`	`(str, optional)`	If set, only delete when the existing object's ETag matches.

`delete_many(paths)` #

Delete an explicit collection of paths with default delete options.

Notes

This method collects the iterable and converts its Python path objects before deletion starts, using memory proportional to the number of paths. Empty collections do nothing. Paths that do not exist are ignored. Storage or path-validation errors can leave some paths deleted; this operation is not atomic and does not guarantee a single remote request. Use remove_all to recursively delete a path prefix.

Parameters:

Name	Type	Description	Default
`paths`	`Iterable[str \| PathLike[str]]`	The paths to delete. A single path is not accepted.	required

Returns:

Type	Description
`Awaitable[None]`	An awaitable that completes when deletion finishes.

`exists(path)` #

Check if a path exists.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path to check.	required

Returns:

Type	Description
`coroutine`	An awaitable that returns True if the path exists, False otherwise.

`from_config(config)` `classmethod` #

Create a new AsyncOperator from a typed service config.

The config is an opendal.config.ServiceConfig (e.g. S3Config); its scheme key selects the service, so a static type checker rejects a wrong scheme, a missing required key, an unknown key, and a wrong value type. Non-string values (bool, int, os.PathLike, list) are converted to the string form core consumes.

Parameters:

Name	Type	Description	Default
`config`	`ServiceConfig`	A service configuration such as `opendal.config.S3Config`.	required

Returns:

Type	Description
`AsyncOperator`	The new async operator.

Examples:

import opendal
from opendal.config import S3Config

op = opendal.AsyncOperator.from_config(
    S3Config(scheme="s3", bucket="my-bucket")
)

`from_uri(uri, **kwargs)` `classmethod` #

Create a new AsyncOperator from a URI string.

The URI encodes the scheme and configuration in a single string, e.g. memory:// or s3://bucket/path?region=us-east-1. The scheme must belong to a service enabled in this build. Encode service options as query parameters; use urllib.parse.urlencode when building the URI dynamically.

Parameters:

Name	Type	Description	Default
`uri`	`str`	The URI of the service, including any options as query parameters.	required
`**kwargs`	`dict`	Overrides for URI options. Prefer the URI query string.	`{}`

Returns:

Type	Description
`AsyncOperator`	The new async operator.

Examples:

from urllib.parse import urlencode
import opendal

op = opendal.AsyncOperator.from_uri("memory://")
query = urlencode({"region": "us-east-1"})
op = opendal.AsyncOperator.from_uri(
    f"s3://bucket/path?{query}"
)

`layer(layer)` #

Add a new layer to the operator.

Parameters:

Name	Type	Description	Default
`layer`	`Layer`	The layer to add.	required

Returns:

Type	Description
`AsyncOperator`	A new operator with the layer added.

`list(path, *, limit=None, start_after=None, recursive=None, versions=None, deleted=None)` #

List entries in the given directory.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path to the directory.	required
`limit`	`int`	The maximum number of entries to return.	`None`
`start_after`	`str`	The entry to start after.	`None`
`recursive`	`bool`	Whether to list recursively.	`None`
`versions`	`bool`	Whether to list versions.	`None`
`deleted`	`bool`	Whether to list deleted entries.	`None`

Returns:

Type	Description
`coroutine`	An awaitable that returns an async iterator over the entries.

`open(path, mode, **kwargs)` #

Open an async file-like object for the given path.

The returning async file-like object is a context manager.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path to the file.	required
`mode`	`str`	The mode to open the file in. Only "rb" and "wb" are supported.	required
`**kwargs`	`dict`	Additional options for the underlying reader or writer.	`{}`

Returns:

Type	Description
`coroutine`	An awaitable that returns a file-like object.

`presign_delete(path, expire_second, *, version=None)` #

Create a presigned request for a delete operation.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path of the object to delete.	required
`expire_second`	`int`	The number of seconds until the presigned URL expires.	required
`version`	`str`	The version of the file to delete.	`None`

Returns:

Type	Description
`coroutine`	An awaitable that returns a presigned request object.

`presign_read(path, expire_second, *, version=None, if_match=None, if_none_match=None, if_modified_since=None, if_unmodified_since=None, content_type=None, cache_control=None, content_disposition=None)` #

Create a presigned request for a read operation.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path of the object to read.	required
`expire_second`	`int`	The number of seconds until the presigned URL expires.	required
`version`	`str`	The version of the file.	`None`
`if_match`	`str`	The ETag to match.	`None`
`if_none_match`	`str`	The ETag to not match.	`None`
`if_modified_since`	`datetime`	Only return if modified since this time.	`None`
`if_unmodified_since`	`datetime`	Only return if unmodified since this time.	`None`
`content_type`	`str`	Override the content type in the presigned response.	`None`
`cache_control`	`str`	Override the cache control in the presigned response.	`None`
`content_disposition`	`str`	Override the content disposition in the presigned response.	`None`

Returns:

Type	Description
`coroutine`	An awaitable that returns a presigned request object.

`presign_stat(path, expire_second, *, version=None, if_match=None, if_none_match=None, if_modified_since=None, if_unmodified_since=None, content_type=None, cache_control=None, content_disposition=None)` #

Create a presigned request for a stat operation.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path of the object to stat.	required
`expire_second`	`int`	The number of seconds until the presigned URL expires.	required
`version`	`str`	The version of the file.	`None`
`if_match`	`str`	The ETag to match.	`None`
`if_none_match`	`str`	The ETag to not match.	`None`
`if_modified_since`	`datetime`	Only return if modified since this time.	`None`
`if_unmodified_since`	`datetime`	Only return if unmodified since this time.	`None`
`content_type`	`str`	Override the content type in the presigned response.	`None`
`cache_control`	`str`	Override the cache control in the presigned response.	`None`
`content_disposition`	`str`	Override the content disposition in the presigned response.	`None`

Returns:

Type	Description
`coroutine`	An awaitable that returns a presigned request object.

`presign_write(path, expire_second, *, content_type=None, content_disposition=None, content_encoding=None, cache_control=None, if_match=None, if_none_match=None, if_not_exists=None, user_metadata=None)` #

Create a presigned request for a write operation.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path of the object to write to.	required
`expire_second`	`int`	The number of seconds until the presigned URL expires.	required
`content_type`	`str`	The content type header to set on the file.	`None`
`content_disposition`	`str`	The content disposition header to set on the file.	`None`
`content_encoding`	`str`	The content encoding header to set on the file.	`None`
`cache_control`	`str`	The cache control header to set on the file.	`None`
`if_match`	`str`	The ETag to match when writing the file.	`None`
`if_none_match`	`str`	The ETag to not match when writing the file.	`None`
`if_not_exists`	`bool`	Whether to fail if the file already exists.	`None`
`user_metadata`	`dict`	The user metadata to set on the file.	`None`

Returns:

Type	Description
`coroutine`	An awaitable that returns a presigned request object.

`read(path, *, version=None, concurrent=None, chunk=None, gap=None, offset=None, prefetch=None, size=None, if_match=None, if_none_match=None, if_modified_since=None, if_unmodified_since=None, content_type=None, cache_control=None, content_disposition=None)` #

Read the entire contents of a file at the given path.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path to the file.	required
`version`	`str`	The version of the file.	`None`
`concurrent`	`int`	The number of concurrent readers.	`None`
`chunk`	`int`	The size of each chunk.	`None`
`gap`	`int`	The gap between each chunk.	`None`
`offset`	`int`	The offset of the file.	`None`
`prefetch`	`int`	The number of bytes to prefetch.	`None`
`size`	`int`	The size of the file.	`None`
`if_match`	`str`	The ETag of the file.	`None`
`if_none_match`	`str`	The ETag of the file.	`None`
`if_modified_since`	`str`	The last modified time of the file.	`None`
`if_unmodified_since`	`str`	The last modified time of the file.	`None`
`content_type`	`str`	The content type of the file.	`None`
`cache_control`	`str`	The cache control of the file.	`None`
`content_disposition`	`str`	The content disposition of the file.	`None`

Returns:

Type	Description
`coroutine`	An awaitable that returns the contents of the file as bytes.

`remove_all(path)` #

Recursively remove all files and directories at the given path.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path to remove.	required

Returns:

Type	Description
`coroutine`	An awaitable that completes when the removal is finished.

`rename(source, target)` #

Rename (move) a file from one path to another.

Parameters:

Name	Type	Description	Default
`source`	`str`	The path to the source file.	required
`target`	`str`	The path to the target file.	required

Returns:

Type	Description
`coroutine`	An awaitable that completes when the rename is finished.

`scan(path, *, limit=None, start_after=None, versions=None, deleted=None)` #

Recursively list entries in the given directory.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path to the directory.	required
`limit`	`int`	The maximum number of entries to return.	`None`
`start_after`	`str`	The entry to start after.	`None`
`versions`	`bool`	Whether to list versions.	`None`
`deleted`	`bool`	Whether to list deleted entries.	`None`

Returns:

Type	Description
`coroutine`	An awaitable that returns an async iterator over the entries.

`stat(path, *, version=None, if_match=None, if_none_match=None, if_modified_since=None, if_unmodified_since=None, content_type=None, cache_control=None, content_disposition=None)` #

Get the metadata of a file at the given path.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path to the file.	required
`version`	`str`	The version of the file.	`None`
`if_match`	`str`	The ETag of the file.	`None`
`if_none_match`	`str`	The ETag of the file.	`None`
`if_modified_since`	`datetime`	The last modified time of the file.	`None`
`if_unmodified_since`	`datetime`	The last modified time of the file.	`None`
`content_type`	`str`	The content type of the file.	`None`
`cache_control`	`str`	The cache control of the file.	`None`
`content_disposition`	`str`	The content disposition of the file.	`None`

Returns:

Type	Description
`coroutine`	An awaitable that returns the metadata of the file.

`to_operator()` #

Create a new blocking Operator from this async operator.

Returns:

Type	Description
`Operator`	The blocking operator.

`write(path, bs, *, append=None, chunk=None, concurrent=None, cache_control=None, content_type=None, content_disposition=None, content_encoding=None, if_match=None, if_none_match=None, if_not_exists=None, user_metadata=None)` #

Write bytes to a file at the given path.

This function will create a file if it does not exist, and will overwrite its contents if it does.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path to the file.	required
`bs`	`bytes`	The contents to write to the file.	required
`append`	`bool`	Whether to append to the file instead of overwriting it.	`None`
`chunk`	`int`	The chunk size to use when writing the file.	`None`
`concurrent`	`int`	The number of concurrent requests to make when writing the file.	`None`
`cache_control`	`str`	The cache control header to set on the file.	`None`
`content_type`	`str`	The content type header to set on the file.	`None`
`content_disposition`	`str`	The content disposition header to set on the file.	`None`
`content_encoding`	`str`	The content encoding header to set on the file.	`None`
`if_match`	`str`	The ETag to match when writing the file.	`None`
`if_none_match`	`str`	The ETag to not match when writing the file.	`None`
`if_not_exists`	`bool`	Whether to fail if the file already exists.	`None`
`user_metadata`	`dict`	The user metadata to set on the file.	`None`

Returns:

Type	Description
`coroutine`	An awaitable that completes when the write is finished.

Async operator

__new__(scheme, **kwargs) #

capability() #

check() #

copy(source, target) #

create_dir(path) #

delete(path, *, version=None, recursive=None, if_match=None) #

delete_many(paths) #

exists(path) #

from_config(config) classmethod #

from_uri(uri, **kwargs) classmethod #

layer(layer) #

list(path, *, limit=None, start_after=None, recursive=None, versions=None, deleted=None) #

open(path, mode, **kwargs) #

presign_delete(path, expire_second, *, version=None) #

presign_read(path, expire_second, *, version=None, if_match=None, if_none_match=None, if_modified_since=None, if_unmodified_since=None, content_type=None, cache_control=None, content_disposition=None) #

presign_stat(path, expire_second, *, version=None, if_match=None, if_none_match=None, if_modified_since=None, if_unmodified_since=None, content_type=None, cache_control=None, content_disposition=None) #

presign_write(path, expire_second, *, content_type=None, content_disposition=None, content_encoding=None, cache_control=None, if_match=None, if_none_match=None, if_not_exists=None, user_metadata=None) #

read(path, *, version=None, concurrent=None, chunk=None, gap=None, offset=None, prefetch=None, size=None, if_match=None, if_none_match=None, if_modified_since=None, if_unmodified_since=None, content_type=None, cache_control=None, content_disposition=None) #

remove_all(path) #

rename(source, target) #

scan(path, *, limit=None, start_after=None, versions=None, deleted=None) #

stat(path, *, version=None, if_match=None, if_none_match=None, if_modified_since=None, if_unmodified_since=None, content_type=None, cache_control=None, content_disposition=None) #

to_operator() #

write(path, bs, *, append=None, chunk=None, concurrent=None, cache_control=None, content_type=None, content_disposition=None, content_encoding=None, if_match=None, if_none_match=None, if_not_exists=None, user_metadata=None) #

`new(scheme, **kwargs)` #

`capability()` #

`check()` #

`copy(source, target)` #

`create_dir(path)` #

`delete(path, *, version=None, recursive=None, if_match=None)` #

`delete_many(paths)` #

`exists(path)` #

`from_config(config)` `classmethod` #

`from_uri(uri, **kwargs)` `classmethod` #

`layer(layer)` #

`list(path, *, limit=None, start_after=None, recursive=None, versions=None, deleted=None)` #

`open(path, mode, **kwargs)` #

`presign_delete(path, expire_second, *, version=None)` #

`presign_read(path, expire_second, *, version=None, if_match=None, if_none_match=None, if_modified_since=None, if_unmodified_since=None, content_type=None, cache_control=None, content_disposition=None)` #

`presign_stat(path, expire_second, *, version=None, if_match=None, if_none_match=None, if_modified_since=None, if_unmodified_since=None, content_type=None, cache_control=None, content_disposition=None)` #

`presign_write(path, expire_second, *, content_type=None, content_disposition=None, content_encoding=None, cache_control=None, if_match=None, if_none_match=None, if_not_exists=None, user_metadata=None)` #

`read(path, *, version=None, concurrent=None, chunk=None, gap=None, offset=None, prefetch=None, size=None, if_match=None, if_none_match=None, if_modified_since=None, if_unmodified_since=None, content_type=None, cache_control=None, content_disposition=None)` #

`remove_all(path)` #

`rename(source, target)` #

`scan(path, *, limit=None, start_after=None, versions=None, deleted=None)` #

`stat(path, *, version=None, if_match=None, if_none_match=None, if_modified_since=None, if_unmodified_since=None, content_type=None, cache_control=None, content_disposition=None)` #

`to_operator()` #

`write(path, bs, *, append=None, chunk=None, concurrent=None, cache_control=None, content_type=None, content_disposition=None, content_encoding=None, if_match=None, if_none_match=None, if_not_exists=None, user_metadata=None)` #