suyanhanx commented on code in PR #2861:
URL:
https://github.com/apache/incubator-opendal/pull/2861#discussion_r1293065640
##########
core/src/types/operator/blocking_operator.rs:
##########
@@ -134,7 +129,8 @@ impl BlockingOperator {
/// # use opendal::BlockingOperator;
/// use opendal::ErrorKind;
/// #
- /// # fn test(op: BlockingOperator) -> Result<()> {
+ /// # #[tokio::main]
+ /// # async fn test(op: BlockingOperator) -> Result<()> {
Review Comment:
Remove this async?
##########
core/src/types/operator/blocking_operator.rs:
##########
@@ -715,106 +711,329 @@ impl BlockingOperator {
Ok(())
}
- /// List current dir path.
+ /// List entries within a given directory.
///
- /// This function will create a new handle to list entries.
+ /// # Notes
+ ///
+ /// ## Listing recursively
+ ///
+ /// This function only read the children of the given directory. To read
+ /// all entries recursively, use
`BlockingOperator::list_with("path").delimiter("")`
+ /// instead.
+ ///
+ /// ## Streaming
+ ///
+ /// 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 [`BlockingOperator::lister`] to
list entries in
+ /// a streaming way.
///
- /// An error will be returned if path doesn't end with `/`.
+ /// ## Metadata
+ ///
+ /// The only metadata that is guaranteed to be available is the `Mode`.
+ /// For fetching more metadata, please use [`BlockingOperator::list_with`]
and `metakey`.
///
/// # Examples
///
/// ```no_run
- /// # use opendal::Result;
- /// # use futures::io;
- /// # use opendal::BlockingOperator;
- /// # use opendal::EntryMode;
+ /// # use anyhow::Result;
+ /// use opendal::EntryMode;
+ /// use opendal::Metakey;
+ /// use opendal::BlockingOperator;
+ /// # fn test(op: BlockingOperator) -> Result<()> {
+ /// let mut entries = op.list("path/to/dir/")?;
+ /// for entry in entries {
+ /// match entry.metadata().mode() {
+ /// EntryMode::FILE => {
+ /// println!("Handling file")
+ /// }
+ /// EntryMode::DIR => {
+ /// println!("Handling dir {}", entry.path())
+ /// }
+ /// EntryMode::Unknown => continue,
+ /// }
+ /// }
+ /// # Ok(())
+ /// # }
+ /// ```
+ pub fn list(&self, path: &str) -> Result<Vec<Entry>> {
+ self.list_with(path).call()
+ }
+
+ /// List entries within a given directory with options.
+ ///
+ /// # Notes
+ ///
+ /// ## For streaming
+ ///
+ /// 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 [`Operator::lister`] to list
entries in
+ /// a streaming way.
+ ///
+ /// ## Metadata
+ ///
+ /// The only metadata that is guaranteed to be available is the `Mode`.
+ /// For fetching more metadata, please specify the `metakey`.
+ ///
+ /// # Examples
+ ///
+ /// ## List entries with prefix
+ ///
+ /// This function can also be used to list entries in recursive way.
+ ///
+ /// ```no_run
+ /// # use anyhow::Result;
+ /// use opendal::EntryMode;
+ /// use opendal::Metakey;
+ /// use opendal::BlockingOperator;
/// # fn test(op: BlockingOperator) -> Result<()> {
- /// let mut ds = op.list("path/to/dir/")?;
- /// while let Some(mut entry) = ds.next() {
- /// let entry = entry?;
+ /// let mut entries = op.list_with("prefix/").delimiter("").call()?;
+ /// for entry in entries {
+ /// match entry.metadata().mode() {
+ /// EntryMode::FILE => {
+ /// println!("Handling file")
+ /// }
+ /// EntryMode::DIR => {
+ /// println!("Handling dir like start a new list via
meta.path()")
+ /// }
+ /// EntryMode::Unknown => continue,
+ /// }
+ /// }
+ /// # Ok(())
+ /// # }
+ /// ```
+ ///
+ /// ## List entries with metakey for more metadata
+ ///
+ /// ```no_run
+ /// # use anyhow::Result;
+ /// use opendal::EntryMode;
+ /// use opendal::Metakey;
+ /// use opendal::BlockingOperator;
+ /// # fn test(op: BlockingOperator) -> Result<()> {
+ /// let mut entries = op
+ /// .list_with("dir/")
+ /// .metakey(Metakey::ContentLength | Metakey::LastModified)
+ /// .call()?;
+ /// for entry in entries {
/// let meta = entry.metadata();
/// match meta.mode() {
/// EntryMode::FILE => {
- /// println!("Handling file")
+ /// println!(
+ /// "Handling file {} with size {}",
+ /// entry.path(),
+ /// meta.content_length()
+ /// )
/// }
/// EntryMode::DIR => {
- /// println!("Handling dir like start a new list via
de.path()")
+ /// println!("Handling dir {}", entry.path())
/// }
/// EntryMode::Unknown => continue,
/// }
/// }
/// # Ok(())
/// # }
/// ```
- pub fn list(&self, path: &str) -> Result<BlockingLister> {
+ pub fn list_with(&self, path: &str) -> FunctionList {
let path = normalize_path(path);
- if !validate_path(&path, EntryMode::DIR) {
- return Err(Error::new(
- ErrorKind::NotADirectory,
- "the path trying to list should end with `/`",
- )
- .with_operation("BlockingOperator::list")
- .with_context("service", self.info().scheme().into_static())
- .with_context("path", &path));
- }
+ FunctionList(OperatorFunction::new(
+ self.inner().clone(),
+ path,
+ OpList::default(),
+ |inner, path, args| {
+ if !validate_path(&path, EntryMode::FILE) {
+ return Err(
+ Error::new(ErrorKind::IsADirectory, "write path is a
directory")
+ .with_operation("BlockingOperator::write_with")
+ .with_context("service",
inner.info().scheme().into_static())
+ .with_context("path", &path),
+ );
+ }
+
+ let (_, pager) = inner.blocking_list(&path, args)?;
+ let lister = BlockingLister::new(pager);
- let (_, pager) = self.inner().blocking_list(&path, OpList::new())?;
- Ok(BlockingLister::new(pager))
+ lister.collect()
+ },
+ ))
}
- /// List dir in flat way.
+ /// List entries within a given directory as an iterator.
///
- /// Also, this function can be used to list a prefix.
+ /// This function will create a new handle to list entries.
///
/// An error will be returned if given path doesn't end with `/`.
///
/// # Notes
///
- /// - `scan` will not return the prefix itself.
- /// - `scan` is an alias of `list_with(OpList::new().with_delimiter(""))`
+ /// ## Listing recursively
+ ///
+ /// This function only read the children of the given directory. To read
+ /// all entries recursively, use [`BlockingOperator::lister_with`] and
`delimiter("")`
+ /// instead.
+ ///
+ /// ## Metadata
+ ///
+ /// The only metadata that is guaranteed to be available is the `Mode`.
+ /// For fetching more metadata, please use
[`BlockingOperator::lister_with`] and `metakey`.
///
/// # Examples
///
/// ```no_run
- /// # use opendal::Result;
+ /// # use anyhow::Result;
/// # use futures::io;
- /// # use opendal::BlockingOperator;
- /// # use opendal::EntryMode;
+ /// use futures::TryStreamExt;
+ /// use opendal::EntryMode;
+ /// use opendal::Metakey;
+ /// use opendal::BlockingOperator;
+ /// # async fn test(op: BlockingOperator) -> Result<()> {
Review Comment:
ditto
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
