fix(bindings/python): fix type annotations and improve docs (#3483)

bindings/python/python/opendal/__init__.pyi

@@ -17,6 +17,8 @@
 
 from typing import AsyncIterable, Iterable, Optional
 
+from opendal.layers import Layer
+
 class Error(Exception): ...
 
 class Operator:
@@ -28,11 +30,11 @@ class Operator:
         self,
         path: str,
         bs: bytes,
-        append: bool = None,
-        buffer: int = None,
-        content_type: str = None,
-        content_disposition: str = None,
-        cache_control: str = None,
+        append: Optional[bool] = None,
+        buffer: Optional[int] = None,
+        content_type: Optional[str] = None,
+        content_disposition: Optional[str] = None,
+        cache_control: Optional[str] = None,
     ): ...
     def stat(self, path: str) -> Metadata: ...
     def create_dir(self, path: str): ...
@@ -53,11 +55,11 @@ class AsyncOperator:
         self,
         path: str,
         bs: bytes,
-        append: bool = None,
-        buffer: int = None,
-        content_type: str = None,
-        content_disposition: str = None,
-        cache_control: str = None,
+        append: Optional[bool] = None,
+        buffer: Optional[int] = None,
+        content_type: Optional[str] = None,
+        content_disposition: Optional[str] = None,
+        cache_control: Optional[str] = None,
     ): ...
     async def stat(self, path: str) -> Metadata: ...
     async def create_dir(self, path: str): ...

bindings/python/python/opendal/layers.pyi

@@ -15,12 +15,17 @@
 # specific language governing permissions and limitations
 # under the License.
 
-class RetryLayer:
+from typing import Optional
+
+class Layer:
+    pass
+
+class RetryLayer(Layer):
     def __init__(
         self,
-        max_times: int | None = None,
-        factor: float | None = None,
+        max_times: Optional[int] = None,
+        factor: Optional[float] = None,
         jitter: bool = False,
-        max_delay: float | None = None,
-        min_delay: float | None = None,
+        max_delay: Optional[float] = None,
+        min_delay: Optional[float] = None,
     ) -> None: ...

bindings/python/src/capability.rs

@@ -17,47 +17,107 @@
 
 use pyo3::prelude::*;
 
+/// Capability is used to describe what operations are supported
+/// by current Operator.
 #[pyclass(get_all, module = "opendal")]
 pub struct Capability {
+    /// If operator supports stat.
     pub stat: bool,
+    /// If operator supports stat with if match.
     pub stat_with_if_match: bool,
+    /// If operator supports stat with if none match.
     pub stat_with_if_none_match: bool,
+
+    /// If operator supports read.
     pub read: bool,
+    /// If operator supports seek on returning reader.
     pub read_can_seek: bool,
+    /// If operator supports next on returning reader.
     pub read_can_next: bool,
+    /// If operator supports read with range.
     pub read_with_range: bool,
+    /// If operator supports read with if match.
     pub read_with_if_match: bool,
+    /// If operator supports read with if none match.
     pub read_with_if_none_match: bool,
+    /// if operator supports read with override cache control.
     pub read_with_override_cache_control: bool,
+    /// if operator supports read with override content disposition.
     pub read_with_override_content_disposition: bool,
+    /// if operator supports read with override content type.
     pub read_with_override_content_type: bool,
+
+    /// If operator supports write.
     pub write: bool,
+    /// If operator supports write can be called in multi times.
     pub write_can_multi: bool,
+    /// If operator supports write with empty content.
     pub write_can_empty: bool,
+    /// If operator supports write by append.
     pub write_can_append: bool,
+    /// If operator supports write with content type.
     pub write_with_content_type: bool,
+    /// If operator supports write with content disposition.
     pub write_with_content_disposition: bool,
+    /// If operator supports write with cache control.
     pub write_with_cache_control: bool,
+    /// write_multi_max_size is the max size that services support in write_multi.
+    ///
+    /// For example, AWS S3 supports 5GiB as max in write_multi.
     pub write_multi_max_size: Option<usize>,
+    /// write_multi_min_size is the min size that services support in write_multi.
+    ///
+    /// For example, AWS S3 requires at least 5MiB in write_multi expect the last one.
     pub write_multi_min_size: Option<usize>,
+    /// write_multi_align_size is the align size that services required in write_multi.
+    ///
+    /// For example, Google GCS requires align size to 256KiB in write_multi.
     pub write_multi_align_size: Option<usize>,
+    /// write_total_max_size is the max size that services support in write_total.
+    ///
+    /// For example, Cloudflare D1 supports 1MB as max in write_total.
     pub write_total_max_size: Option<usize>,
+
+    /// If operator supports create dir.
     pub create_dir: bool,
+
+    /// If operator supports delete.
     pub delete: bool,
+
+    /// If operator supports copy.
     pub copy: bool,
+
+    /// If operator supports rename.
     pub rename: bool,
+
+    /// If operator supports list.
     pub list: bool,
+    /// If backend supports list with limit.
     pub list_with_limit: bool,
+    /// If backend supports list with start after.
     pub list_with_start_after: bool,
+    /// If backend support list with using slash as delimiter.
     pub list_with_delimiter_slash: bool,
+    /// If backend supports list without delimiter.
     pub list_without_delimiter: bool,
+
+    /// If operator supports presign.
     pub presign: bool,
+    /// If operator supports presign read.
     pub presign_read: bool,
+    /// If operator supports presign stat.
     pub presign_stat: bool,
+    /// If operator supports presign write.
     pub presign_write: bool,
+
+    /// If operator supports batch.
     pub batch: bool,
+    /// If operator supports batch delete.
     pub batch_delete: bool,
+    /// The max operations that operator supports in batch.
     pub batch_max_operations: Option<usize>,
+
+    /// If operator supports blocking.
     pub blocking: bool,
 }
 

bindings/python/tests/test_async_delete.py

@@ -45,4 +45,4 @@ async def test_async_remove_all(service_name, operator, async_operator):
         if not path.endswith("/"):
             with pytest.raises(FileNotFoundError) as e_info:
                 await async_operator.read(f"{parent}/{path}")
-    await async_operator.remove_all(f"{parent}/")
+    await async_operator.remove_all(f"{parent}/")

bindings/python/tests/test_read.py

@@ -35,6 +35,7 @@ def test_sync_read(service_name, operator, async_operator):
 
     operator.delete(filename)
 
+
 @pytest.mark.need_capability("read", "write", "delete")
 def test_sync_reader(service_name, operator, async_operator):
     size = randint(1, 1024)
@@ -49,6 +50,7 @@ def test_sync_reader(service_name, operator, async_operator):
 
     operator.delete(filename)
 
+
 @pytest.mark.asyncio
 @pytest.mark.need_capability("read", "write", "delete")
 async def test_async_read(service_name, operator, async_operator):
@@ -63,6 +65,7 @@ async def test_async_read(service_name, operator, async_operator):
 
     await async_operator.delete(filename)
 
+
 @pytest.mark.asyncio
 @pytest.mark.need_capability("read", "write", "delete")
 async def test_async_reader(service_name, operator, async_operator):
@@ -78,6 +81,7 @@ async def test_async_reader(service_name, operator, async_operator):
 
     await async_operator.delete(filename)
 
+
 @pytest.mark.asyncio
 @pytest.mark.need_capability("read", "write", "delete")
 async def test_async_reader_without_context(service_name, operator, async_operator):
@@ -94,6 +98,7 @@ async def test_async_reader_without_context(service_name, operator, async_operat
 
     await async_operator.delete(filename)
 
+
 @pytest.mark.need_capability("read", "write", "delete", "stat")
 def test_sync_read_stat(service_name, operator, async_operator):
     size = randint(1, 1024)