This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/opendal.git
The following commit(s) were added to refs/heads/main by this push:
new 5a3df3575 docs: Make it clear that opendal list returns prefix (#6835)
5a3df3575 is described below
commit 5a3df3575d2b256fceb5a9ac200826b767e8dc94
Author: Xuanwo <[email protected]>
AuthorDate: Sun Nov 30 23:53:35 2025 +0800
docs: Make it clear that opendal list returns prefix (#6835)
---
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,
}
