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/incubator-opendal.git
The following commit(s) were added to refs/heads/main by this push:
new b3f8da7b8 chore: Polish comments for `stat` and `stat_with` (#3657)
b3f8da7b8 is described below
commit b3f8da7b8acd9882992d1e2b69b4b6231dfa3337
Author: Xuanwo <[email protected]>
AuthorDate: Thu Nov 23 17:27:47 2023 +0800
chore: Polish comments for `stat` and `stat_with` (#3657)
* Fix comments
Signed-off-by: Xuanwo <[email protected]>
* Fix binding c
Signed-off-by: Xuanwo <[email protected]>
* Fix doc
Signed-off-by: Xuanwo <[email protected]>
* Add upgrade
Signed-off-by: Xuanwo <[email protected]>
---------
Signed-off-by: Xuanwo <[email protected]>
---
bindings/c/tests/bdd.cpp | 1 -
bindings/c/tests/opinfo.cpp | 54 +++++++++++++++-------------
core/src/docs/upgrade.md | 18 ++++++++++
core/src/raw/oio/list/api.rs | 2 +-
core/src/types/operator/blocking_operator.rs | 16 +++++++++
core/src/types/operator/operator.rs | 16 +++++++++
6 files changed, 80 insertions(+), 27 deletions(-)
diff --git a/bindings/c/tests/bdd.cpp b/bindings/c/tests/bdd.cpp
index 1de64da79..67b8f56b8 100644
--- a/bindings/c/tests/bdd.cpp
+++ b/bindings/c/tests/bdd.cpp
@@ -102,7 +102,6 @@ TEST_F(OpendalBddTest, FeatureTest)
EXPECT_FALSE(opendal_metadata_last_modified_ms(meta) != -1);
opendal_metadata_free(meta);
-
// The blocking file "test" must have content "Hello, World!"
struct opendal_result_read r = opendal_operator_read(this->p,
this->path.c_str());
EXPECT_EQ(r.error, nullptr);
diff --git a/bindings/c/tests/opinfo.cpp b/bindings/c/tests/opinfo.cpp
index 56e0bae3f..480364017 100644
--- a/bindings/c/tests/opinfo.cpp
+++ b/bindings/c/tests/opinfo.cpp
@@ -62,32 +62,36 @@ TEST_F(OpendalOperatorInfoTest, CapabilityTest)
{
opendal_capability full_cap =
opendal_operator_info_get_full_capability(this->info);
opendal_capability native_cap =
opendal_operator_info_get_native_capability(this->info);
- opendal_capability caps[2] = { full_cap, native_cap };
- for (int i = 0; i < 2; ++i) {
- opendal_capability cap = caps[i];
-
- EXPECT_TRUE(cap.blocking);
-
- EXPECT_TRUE(cap.read);
- EXPECT_TRUE(cap.read_can_seek);
- EXPECT_TRUE(cap.read_can_next);
- EXPECT_TRUE(cap.read_with_range);
- EXPECT_TRUE(cap.stat);
-
- EXPECT_TRUE(cap.write);
- EXPECT_TRUE(cap.write_can_empty);
- EXPECT_TRUE(cap.create_dir);
-
- EXPECT_TRUE(cap.delete_);
-
- EXPECT_TRUE(cap.list);
- EXPECT_TRUE(cap.list_with_recursive);
-
- EXPECT_TRUE(cap.copy);
-
- EXPECT_TRUE(cap.rename);
- }
+ EXPECT_TRUE(full_cap.blocking);
+ EXPECT_TRUE(full_cap.read);
+ EXPECT_TRUE(full_cap.read_can_seek);
+ EXPECT_TRUE(full_cap.read_can_next);
+ EXPECT_TRUE(full_cap.read_with_range);
+ EXPECT_TRUE(full_cap.stat);
+ EXPECT_TRUE(full_cap.write);
+ EXPECT_TRUE(full_cap.write_can_empty);
+ EXPECT_TRUE(full_cap.create_dir);
+ EXPECT_TRUE(full_cap.delete_);
+ EXPECT_TRUE(full_cap.list);
+ EXPECT_TRUE(full_cap.list_with_recursive);
+ EXPECT_TRUE(full_cap.copy);
+ EXPECT_TRUE(full_cap.rename);
+
+ EXPECT_TRUE(native_cap.blocking);
+ EXPECT_TRUE(native_cap.read);
+ EXPECT_TRUE(native_cap.read_can_seek);
+ EXPECT_TRUE(native_cap.read_can_next);
+ EXPECT_TRUE(native_cap.read_with_range);
+ EXPECT_TRUE(native_cap.stat);
+ EXPECT_TRUE(native_cap.write);
+ EXPECT_TRUE(native_cap.write_can_empty);
+ EXPECT_FALSE(native_cap.create_dir);
+ EXPECT_TRUE(native_cap.delete_);
+ EXPECT_TRUE(native_cap.list);
+ EXPECT_TRUE(native_cap.list_with_recursive);
+ EXPECT_TRUE(native_cap.copy);
+ EXPECT_TRUE(native_cap.rename);
}
TEST_F(OpendalOperatorInfoTest, InfoTest)
diff --git a/core/src/docs/upgrade.md b/core/src/docs/upgrade.md
index ba3a12f79..faf8a59af 100644
--- a/core/src/docs/upgrade.md
+++ b/core/src/docs/upgrade.md
@@ -2,6 +2,8 @@
## Public API
+### List Recursive
+
After [RFC-3526: List Recursive](crate::docs::rfcs::rfc_3526_list_recursive)
landed, we have changed the `list` API to accept `recursive` instead of
`delimiter`:
Users will need to change the following usage:
@@ -11,6 +13,22 @@ Users will need to change the following usage:
`delimiter` other than `""` and `"/"` is not supported anymore.
+### Stat a dir path
+
+After [RFC: List Prefix](crate::docs::rfcs::rfc_3243_list_prefix) landed, we
have changed the behavior of `stat` a dir path:
+
+Here are the behavior list:
+
+| Case | Path | Result
|
+|------------------------|-----------------|--------------------------------------------|
+| stat existing dir | `abc/` | Metadata with dir mode
|
+| stat existing file | `abc/def_file` | Metadata with file mode
|
+| stat dir without `/` | `abc/def_dir` | Error `NotFound` or metadata with
dir mode |
+| stat file with `/` | `abc/def_file/` | Error `NotFound`
|
+| stat not existing path | `xyz` | Error `NotFound`
|
+
+Services like s3, azblob can handle `stat("abc/")` correctly by check if there
are objects with prefix `abc/`.
+
## Raw API
### Lister Align
diff --git a/core/src/raw/oio/list/api.rs b/core/src/raw/oio/list/api.rs
index 55dd2ff31..6130aa914 100644
--- a/core/src/raw/oio/list/api.rs
+++ b/core/src/raw/oio/list/api.rs
@@ -97,7 +97,7 @@ impl<P: List> List for Option<P> {
/// Impl ListExt for all T: List
impl<T: List> ListExt for T {}
-/// Extension of [`Read`] to make it easier for use.
+/// Extension of [`List`] to make it easier for use.
pub trait ListExt: List {
/// Build a future for `poll_next`.
fn next(&mut self) -> NextFuture<Self> {
diff --git a/core/src/types/operator/blocking_operator.rs
b/core/src/types/operator/blocking_operator.rs
index a4165fd10..f811eeedb 100644
--- a/core/src/types/operator/blocking_operator.rs
+++ b/core/src/types/operator/blocking_operator.rs
@@ -152,6 +152,8 @@ impl BlockingOperator {
///
/// # Behavior
///
+ /// ## Services that support `create_dir`
+ ///
/// `test` and `test/` may vary in some services such as S3. However, on a
local file system,
/// they're identical. Therefore, the behavior of `stat("test")` and
`stat("test/")` might differ
/// in certain edge cases. Always use `stat("test/")` when you need to
access a directory if possible.
@@ -168,6 +170,12 @@ impl BlockingOperator {
///
/// Refer to [RFC: List Prefix][crate::docs::rfcs::rfc_3243_list_prefix]
for more details.
///
+ /// ## Services that not support `create_dir`
+ ///
+ /// For services that not support `create_dir`, `stat("test/")` will
return `NotFound` even
+ /// when `test/abc` exists since the service won't have the concept of
dir. There is nothing
+ /// we can do about this.
+ ///
/// # Examples
///
/// ## Check if file exists
@@ -201,6 +209,8 @@ impl BlockingOperator {
///
/// # Behavior
///
+ /// ## Services that support `create_dir`
+ ///
/// `test` and `test/` may vary in some services such as S3. However, on a
local file system,
/// they're identical. Therefore, the behavior of `stat("test")` and
`stat("test/")` might differ
/// in certain edge cases. Always use `stat("test/")` when you need to
access a directory if possible.
@@ -217,6 +227,12 @@ impl BlockingOperator {
///
/// Refer to [RFC: List Prefix][crate::docs::rfcs::rfc_3243_list_prefix]
for more details.
///
+ /// ## Services that not support `create_dir`
+ ///
+ /// For services that not support `create_dir`, `stat("test/")` will
return `NotFound` even
+ /// when `test/abc` exists since the service won't have the concept of
dir. There is nothing
+ /// we can do about this.
+ ///
/// # Examples
///
/// ## Get metadata while `ETag` matches
diff --git a/core/src/types/operator/operator.rs
b/core/src/types/operator/operator.rs
index 7ca46cfb7..c0f08d515 100644
--- a/core/src/types/operator/operator.rs
+++ b/core/src/types/operator/operator.rs
@@ -168,6 +168,8 @@ impl Operator {
///
/// # Behavior
///
+ /// ## Services that support `create_dir`
+ ///
/// `test` and `test/` may vary in some services such as S3. However, on a
local file system,
/// they're identical. Therefore, the behavior of `stat("test")` and
`stat("test/")` might differ
/// in certain edge cases. Always use `stat("test/")` when you need to
access a directory if possible.
@@ -184,6 +186,12 @@ impl Operator {
///
/// Refer to [RFC: List Prefix][crate::docs::rfcs::rfc_3243_list_prefix]
for more details.
///
+ /// ## Services that not support `create_dir`
+ ///
+ /// For services that not support `create_dir`, `stat("test/")` will
return `NotFound` even
+ /// when `test/abc` exists since the service won't have the concept of
dir. There is nothing
+ /// we can do about this.
+ ///
/// # Examples
///
/// ## Check if file exists
@@ -218,6 +226,8 @@ impl Operator {
///
/// # Behavior
///
+ /// ## Services that support `create_dir`
+ ///
/// `test` and `test/` may vary in some services such as S3. However, on a
local file system,
/// they're identical. Therefore, the behavior of `stat("test")` and
`stat("test/")` might differ
/// in certain edge cases. Always use `stat("test/")` when you need to
access a directory if possible.
@@ -234,6 +244,12 @@ impl Operator {
///
/// Refer to [RFC: List Prefix][crate::docs::rfcs::rfc_3243_list_prefix]
for more details.
///
+ /// ## Services that not support `create_dir`
+ ///
+ /// For services that not support `create_dir`, `stat("test/")` will
return `NotFound` even
+ /// when `test/abc` exists since the service won't have the concept of
dir. There is nothing
+ /// we can do about this.
+ ///
/// # Examples
///
/// ## Get metadata while `ETag` matches
