Operator

The blocking equivalent of AsyncOperator.

Operator is the entry point for all blocking APIs.

`new(scheme, **kwargs)` #

Create a new blocking Operator.

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
`Operator`	The new 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.

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

`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

`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
`version`	`str`	The version of the file to delete. Only supported on version-aware backends.	`None`
`recursive`	`bool`	If True, delete the path recursively. Only supported on backends that support recursive delete.	`None`
`if_match`	`str`	If set, only delete when the existing object's ETag matches.	`None`

`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

`exists(path)` #

Check if a path exists.

Parameters:

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

Returns:

Type	Description
`bool`	True if the path exists, False otherwise.

`from_config(config)` `classmethod` #

Create a new blocking Operator 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
`Operator`	The new operator.

Examples:

import opendal
from opendal.config import S3Config

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

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

Create a new blocking Operator 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
`Operator`	The new operator.

Examples:

from urllib.parse import urlencode
import opendal

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

`layer(layer)` #

Add a new layer to this operator.

Parameters:

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

Returns:

Type	Description
`Operator`	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
`BlockingLister`	An iterator over the entries in the directory.

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

Open a file-like object for the given path.

The returning 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`	`Unpack[OpenKwargs]`	Additional options for the underlying reader or writer.	`{}`

Returns:

Type	Description
`File`	A file-like 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
`bytes`	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

`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

`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
`BlockingLister`	An iterator over the entries in the directory.

`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
`Metadata`	The metadata of the file.

`to_async_operator()` #

Create a new AsyncOperator from this blocking operator.

Returns:

Type	Description
`AsyncOperator`	The async 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`

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) #

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_async_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)` #

`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_async_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)` #