This is an automated email from the ASF dual-hosted git repository. xuanwo pushed a commit to branch xuanwo/list-prefix-semantics in repository https://gitbox.apache.org/repos/asf/opendal.git
commit 9612f9eec08fc8b79cbec702c3786f3c5f53d23c Author: Xuanwo <[email protected]> AuthorDate: Sun Nov 30 02:39:32 2025 +0800 docs: Make it clear that opendal list returns prefix Signed-off-by: Xuanwo <[email protected]> --- core/src/blocking/operator.rs | 58 ++++++++++++++---------------- core/src/types/operator/operator.rs | 71 +++++++++++++++++++++---------------- core/src/types/options.rs | 33 +++++------------ 3 files changed, 77 insertions(+), 85 deletions(-) diff --git a/core/src/blocking/operator.rs b/core/src/blocking/operator.rs index 037b65a19..7b729020e 100644 --- a/core/src/blocking/operator.rs +++ b/core/src/blocking/operator.rs @@ -575,24 +575,18 @@ impl Operator { self.handle.block_on(self.op.remove_all(path)) } - /// List entries that starts with given `path` in parent dir. + /// List entries whose paths start with the given prefix `path`. /// - /// # Notes - /// - /// ## Recursively List + /// # Semantics /// - /// This function only read the children of the given directory. To read - /// all entries recursively, use `blocking::Operator::list_options("path", opts)` - /// instead. + /// - Listing is **prefix-based**; it doesn't require the parent directory to exist. + /// - If `path` itself exists, it is returned as an entry along with prefixed children. + /// - If `path` is missing but deeper objects exist, the list succeeds and returns those prefixed entries instead of an error. + /// - Set `recursive` in [`options::ListOptions`] via [`list_options`](Self::list_options) to walk all descendants; the default returns only immediate children when delimiter is supported. /// /// ## Streaming List /// - /// This function will read all entries in the given directory. It could - /// take very long time and consume a lot of memory if the directory - /// contains a lot of entries. - /// - /// In order to avoid this, you can use [`blocking::Operator::lister`] to list entries in - /// a streaming way. + /// This function materializes the full result in memory. For large listings, prefer [`blocking::Operator::lister`] to stream entries. /// /// # Examples /// @@ -621,34 +615,34 @@ impl Operator { self.list_options(path, options::ListOptions::default()) } - /// List entries that starts with given `path` in parent dir. with options. + /// List entries whose paths start with the given prefix `path` with additional options. /// - /// # Notes + /// # Semantics + /// + /// Inherits the prefix semantics described in [`Operator::list`] (blocking variant). It returns `path` itself if present and tolerates missing parents when prefixed objects exist. /// /// ## Streaming List /// - /// This function will read all entries in the given directory. It could - /// take very long time and consume a lot of memory if the directory - /// contains a lot of entries. + /// This function materializes the full result in memory. For large listings, prefer [`blocking::Operator::lister`] to stream entries. /// - /// In order to avoid this, you can use [`blocking::Operator::lister`] to list entries in - /// a streaming way. + /// ## Options + /// + /// See [`options::ListOptions`] for the full set. Common knobs: traversal (`recursive`), pagination (`limit`, `start_after`), and versioning (`versions`, `deleted`). pub fn list_options(&self, path: &str, opts: options::ListOptions) -> Result<Vec<Entry>> { self.handle.block_on(self.op.list_options(path, opts)) } - /// List entries that starts with given `path` in parent dir. + /// Create a streaming lister for entries whose paths start with the given prefix `path`. /// - /// This function will create a new [`BlockingLister`] to list entries. Users can stop listing - /// via dropping this [`Lister`]. + /// This function creates a new [`BlockingLister`]; dropping it stops listing. /// - /// # Notes + /// # Semantics /// - /// ## Recursively List + /// Shares the same prefix semantics as [`blocking::Operator::list`]: parent directory is optional; `path` itself is yielded if present; missing parents with deeper objects are accepted. /// - /// This function only read the children of the given directory. To read - /// all entries recursively, use [`blocking::Operator::lister_with`] and `delimiter("")` - /// instead. + /// ## Options + /// + /// Accepts the same [`options::ListOptions`] as [`list_options`](Self::list_options): traversal (`recursive`), pagination (`limit`, `start_after`), and versioning (`versions`, `deleted`). /// /// # Examples /// @@ -680,11 +674,13 @@ impl Operator { self.lister_options(path, options::ListOptions::default()) } - /// List entries within a given directory as an iterator with options. + /// List entries under a prefix as an iterator with options. + /// + /// This function creates a new handle to stream entries and inherits the prefix semantics of [`blocking::Operator::list`]. /// - /// This function will create a new handle to list entries. + /// ## Options /// - /// An error will be returned if given path doesn't end with `/`. + /// Same as [`lister`](Self::lister); see [`options::ListOptions`] for traversal, pagination, and versioning knobs. pub fn lister_options( &self, path: &str, diff --git a/core/src/types/operator/operator.rs b/core/src/types/operator/operator.rs index 347dece2d..c033e34c0 100644 --- a/core/src/types/operator/operator.rs +++ b/core/src/types/operator/operator.rs @@ -1466,20 +1466,17 @@ impl Operator { Ok(()) } - /// List entries in the parent directory that start with the specified `path`. + /// List entries whose paths start with the given prefix `path`. /// - /// # Notes - /// - /// ## Recursively List + /// # Semantics /// - /// This function only reads the immediate children of the specified directory. - /// To list all entries recursively, use `Operator::list_with("path").recursive(true)` instead. + /// - Listing is **prefix-based**. It does not require the parent directory to exist. + /// - If `path` itself exists (file or dir), it will be returned as an entry in addition to any prefixed children. + /// - If `path` is absent but deeper objects exist (e.g. `path/child`), the list succeeds and returns those prefixed entries instead of an error. /// /// ## Streaming List /// - /// This function reads all entries in the specified directory. If the directory contains many entries, this process may take a long time and use significant memory. - /// - /// To prevent this, consider using [`Operator::lister`] to stream the entries instead. + /// This function materializes the entire list into memory. For large listings, prefer [`Operator::lister`] to stream entries. /// /// # Examples /// @@ -1509,19 +1506,24 @@ impl Operator { self.list_with(path).await } - /// List entries in the parent directory that start with the specified `path` with additional options. + /// List entries whose paths start with the given prefix `path` with additional options. + /// + /// # Semantics + /// + /// Inherits the prefix semantics described in [`Operator::list`]: returns `path` itself if it exists and tolerates missing parents when prefixed objects exist. /// /// # Notes /// /// ## Streaming List /// - /// This function reads all entries in the specified directory. If the directory contains many entries, this process may take a long time and use significant memory. + /// This function materializes the entire list into memory. For large listings, prefer [`Operator::lister`] to stream entries. /// - /// To prevent this, consider using [`Operator::lister`] to stream the entries instead. + /// ## Options /// - /// # Options - /// - /// Visit [`options::ListOptions`] for all available options. + /// See [`options::ListOptions`] for the full set. Common knobs: + /// - Traversal: `recursive` (default `false`) toggles depth-first listing under the prefix. + /// - Pagination: `limit` and `start_after` tune page size and resume positions (backend dependent). + /// - Versioning: `versions` / `deleted` ask versioned backends to return extra entries. /// /// # Examples /// @@ -1558,19 +1560,19 @@ impl Operator { ) } - /// List entries in the parent directory that start with the specified `path` with additional options. + /// List entries whose paths start with the given prefix `path` using explicit options. /// - /// # Notes + /// # Semantics /// - /// ## Streaming List + /// Same prefix behavior as [`Operator::list`]: returns `path` itself if present and tolerates missing parents when prefixed objects exist. /// - /// This function reads all entries in the specified directory. If the directory contains many entries, this process may take a long time and use significant memory. + /// # Options /// - /// To prevent this, consider using [`Operator::lister`] to stream the entries instead. + /// Accepts [`options::ListOptions`] (see field docs for meaning). /// - /// # Options + /// ## Streaming List /// - /// Visit [`options::ListOptions`] for all available options. + /// Materializes the entire list; use [`Operator::lister`] to stream large result sets. /// /// # Examples /// @@ -1618,14 +1620,15 @@ impl Operator { lister.try_collect().await } - /// Create a new lister to list entries that starts with given `path` in parent dir. + /// Create a streaming lister for entries whose paths start with the given prefix `path`. /// - /// # Notes + /// # Semantics /// - /// ## Recursively list + /// Shares the same prefix semantics as [`Operator::list`]: the parent directory is not required to exist; the entry for `path` is yielded if present; missing parents with deeper objects are accepted. + /// + /// # Options /// - /// This function only reads the immediate children of the specified directory. - /// To retrieve all entries recursively, use [`Operator::lister_with`] with `recursive(true)` instead. + /// Takes the same [`options::ListOptions`] as [`list_with`](Operator::list_with): traversal (`recursive`), pagination (`limit`, `start_after`), and versioning (`versions`, `deleted`). /// /// # Examples /// @@ -1655,11 +1658,11 @@ impl Operator { self.lister_with(path).await } - /// Create a new lister to list entries that starts with given `path` in parent dir with additional options. + /// Create a new lister to list entries that start with the given prefix `path` using additional options. /// /// # Options /// - /// Visit [`options::ListOptions`] for all available options. + /// Same as [`lister_with`](Operator::lister_with); see [`options::ListOptions`] for traversal, pagination, and versioning knobs. /// /// # Examples /// @@ -1697,7 +1700,15 @@ impl Operator { ) } - /// Create a new lister to list entries that starts with given `path` in parent dir with additional options. + /// Create a new lister to list entries that start with the given prefix `path` using additional options. + /// + /// # Semantics + /// + /// Inherits the prefix behavior of [`Operator::lister_with`]. + /// + /// # Options + /// + /// Uses [`options::ListOptions`] to control traversal, pagination, and versioning. /// /// # Examples /// diff --git a/core/src/types/options.rs b/core/src/types/options.rs index f373dd5da..4ef109c61 100644 --- a/core/src/types/options.rs +++ b/core/src/types/options.rs @@ -34,39 +34,24 @@ pub struct DeleteOptions { } /// Options for list operations. +/// +/// # Groups +/// - Traversal: `recursive`. +/// - Pagination: `limit`, `start_after`. +/// - Versioning: `versions`, `deleted` (effective on version-aware backends). #[derive(Debug, Clone, Default, Eq, PartialEq)] pub struct ListOptions { - /// The limit passed to underlying service to specify the max results - /// that could return per-request. - /// - /// Users could use this to control the memory usage of list operation. + /// Maximum results per request (backend hint) to control memory and throttling. pub limit: Option<usize>, /// The start_after passes to underlying service to specify the specified key /// to start listing from. pub start_after: Option<String>, - /// The recursive is used to control whether the list operation is recursive. - /// - /// - If `false`, list operation will only list the entries under the given path. - /// - If `true`, list operation will list all entries that starts with given path. - /// - /// Default to `false`. + /// Whether to list recursively under the prefix; default `false`. pub recursive: bool, - /// The version is used to control whether the object versions should be returned. - /// - /// - If `false`, list operation will not return with object versions - /// - If `true`, list operation will return with object versions if object versioning is supported - /// by the underlying service - /// - /// Default to `false` + /// Include object versions when supported by the backend; default `false`. pub versions: bool, - /// The deleted is used to control whether the deleted objects should be returned. - /// - /// - If `false`, list operation will not return with deleted objects - /// - If `true`, list operation will return with deleted objects if object versioning is supported - /// by the underlying service - /// - /// Default to `false` + /// Include delete markers when supported by version-aware backends; default `false`. pub deleted: bool, }
