feat(bindings/python): Update type annotations (#4630)

bindings/python/python/opendal/__init__.pyi

@@ -15,175 +15,151 @@
 # specific language governing permissions and limitations
 # under the License.
 
-from typing import AsyncIterable, Iterable, Optional
+from typing import Any, AsyncIterable, Iterable, Optional, final, Union, Type
+from types import TracebackType
 
+from opendal import exceptions as exceptions
+from opendal import layers as layers
 from opendal.layers import Layer
 
-
+@final
 class Operator:
-    def __init__(self, scheme: str, **kwargs): ...
-
-    def layer(self, layer: Layer): ...
-
+    def __init__(self, scheme: str, **kwargs: Any) -> None: ...
+    def layer(self, layer: Layer) -> "Operator": ...
     def open(self, path: str, mode: str) -> File: ...
-
-    def read(self, path: str) -> memoryview: ...
-
+    def read(self, path: str) -> bytes: ...
     def write(
         self,
         path: str,
         bs: bytes,
-        append: Optional[bool] = None,
-        buffer: Optional[int] = None,
-        content_type: Optional[str] = None,
-        content_disposition: Optional[str] = None,
-        cache_control: Optional[str] = None,
-    ): ...
-
+        *,
+        append: bool = ...,
+        chunk: int = ...,
+        content_type: str = ...,
+        content_disposition: str = ...,
+        cache_control: str = ...,
+    ) -> None: ...
     def stat(self, path: str) -> Metadata: ...
-
-    def create_dir(self, path: str): ...
-
-    def delete(self, path: str): ...
-
+    def create_dir(self, path: str) -> None: ...
+    def delete(self, path: str) -> None: ...
     def list(self, path: str) -> Iterable[Entry]: ...
-
     def scan(self, path: str) -> Iterable[Entry]: ...
-
     def capability(self) -> Capability: ...
-
-    def copy(self, source: str, target: str): ...
-
-    def rename(self, source: str, target: str): ...
-
-    def remove_all(self, path: str): ...
-
+    def copy(self, source: str, target: str) -> None: ...
+    def rename(self, source: str, target: str) -> None: ...
+    def remove_all(self, path: str) -> None: ...
     def to_async_operator(self) -> AsyncOperator: ...
 
-
+@final
 class AsyncOperator:
-    def __init__(self, scheme: str, **kwargs): ...
-
-    def layer(self, layer: Layer): ...
-
+    def __init__(self, scheme: str, **kwargs: Any) -> None: ...
+    def layer(self, layer: Layer) -> "AsyncOperator": ...
     async def open(self, path: str, mode: str) -> AsyncFile: ...
-
-    async def read(self, path: str) -> memoryview: ...
-
+    async def read(self, path: str) -> bytes: ...
     async def write(
         self,
         path: str,
         bs: bytes,
-        append: Optional[bool] = None,
-        buffer: Optional[int] = None,
-        content_type: Optional[str] = None,
-        content_disposition: Optional[str] = None,
-        cache_control: Optional[str] = None,
-    ): ...
-
+        *,
+        append: bool = ...,
+        chunk: int = ...,
+        content_type: str = ...,
+        content_disposition: str = ...,
+        cache_control: str = ...,
+    ) -> None: ...
     async def stat(self, path: str) -> Metadata: ...
-
-    async def create_dir(self, path: str): ...
-
-    async def delete(self, path: str): ...
-
+    async def create_dir(self, path: str) -> None: ...
+    async def delete(self, path: str) -> None: ...
     async def list(self, path: str) -> AsyncIterable[Entry]: ...
-
     async def scan(self, path: str) -> AsyncIterable[Entry]: ...
-
     async def presign_stat(self, path: str, expire_second: int) -> PresignedRequest: ...
-
     async def presign_read(self, path: str, expire_second: int) -> PresignedRequest: ...
-
     async def presign_write(
         self, path: str, expire_second: int
     ) -> PresignedRequest: ...
-
     def capability(self) -> Capability: ...
-
-    async def copy(self, source: str, target: str): ...
-
-    async def rename(self, source: str, target: str): ...
-
-    async def remove_all(self, path: str): ...
-
+    async def copy(self, source: str, target: str) -> None: ...
+    async def rename(self, source: str, target: str) -> None: ...
+    async def remove_all(self, path: str) -> None: ...
     def to_operator(self) -> Operator: ...
 
-
+@final
 class File:
-    def read(self, size: Optional[int] = None) -> memoryview: ...
-
-    def write(self, bs: bytes): ...
-
-    def seek(self, offset: int, whence: int = 0) -> int: ...
-
+    def read(self, size: Optional[int] = None) -> bytes: ...
+    def write(self, bs: bytes) -> None: ...
+    def seek(self, pos: int, whence: int = 0) -> int: ...
     def tell(self) -> int: ...
-
-    def close(self): ...
-
+    def close(self) -> None: ...
     def __enter__(self) -> File: ...
-
-    def __exit__(self, exc_type, exc_value, traceback) -> None: ...
-
-
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_value: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None: ...
+    @property
+    def closed(self) -> bool: ...
+    def flush(self) -> None: ...
+    def readable(self) -> bool: ...
+    def readinto(self, buffer: Union[bytes, bytearray]) -> int: ...
+    def seekable(self) -> bool: ...
+    def writable(self) -> bool: ...
+
+@final
 class AsyncFile:
-    async def read(self, size: Optional[int] = None) -> memoryview: ...
-
-    async def write(self, bs: bytes): ...
-
-    async def seek(self, offset: int, whence: int = 0) -> int: ...
-
+    async def read(self, size: Optional[int] = None) -> bytes: ...
+    async def write(self, bs: bytes) -> None: ...
+    async def seek(self, pos: int, whence: int = 0) -> int: ...
     async def tell(self) -> int: ...
-
-    async def close(self): ...
-
+    async def close(self) -> None: ...
     def __aenter__(self) -> AsyncFile: ...
+    def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_value: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None: ...
+    @property
+    async def closed(self) -> bool: ...
+    async def readable(self) -> bool: ...
+    async def seekable(self) -> bool: ...
+    async def writable(self) -> bool: ...
 
-    def __aexit__(self, exc_type, exc_value, traceback) -> None: ...
-
-
+@final
 class Entry:
     @property
     def path(self) -> str: ...
 
-
+@final
 class Metadata:
     @property
     def content_disposition(self) -> Optional[str]: ...
-
     @property
     def content_length(self) -> int: ...
-
     @property
     def content_md5(self) -> Optional[str]: ...
-
     @property
     def content_type(self) -> Optional[str]: ...
-
     @property
     def etag(self) -> Optional[str]: ...
-
     @property
     def mode(self) -> EntryMode: ...
 
-
+@final
 class EntryMode:
     def is_file(self) -> bool: ...
-
     def is_dir(self) -> bool: ...
 
-
+@final
 class PresignedRequest:
     @property
     def url(self) -> str: ...
-
     @property
     def method(self) -> str: ...
-
     @property
     def headers(self) -> dict[str, str]: ...
 
-
+@final
 class Capability:
     stat: bool
     stat_with_if_match: bool

bindings/python/python/opendal/layers.pyi

@@ -15,11 +15,12 @@
 # specific language governing permissions and limitations
 # under the License.
 
-from typing import Optional
+from typing import Optional, final
 
 class Layer:
     pass
 
+@final
 class RetryLayer(Layer):
     def __init__(
         self,