feat(bindings/python): Add stubs for some more types (#6703)

* Stubs for Layers

* Stubs for Metadata, Entry, and EntryMode

* Add to API Reference

Author: chitralverma

bindings/python/docs/api/metadata.md bindings/python/docs/api/capability.mdbindings/python/docs/api/metadata.md renamed to bindings/python/docs/api/capability.md

@@ -1,6 +1,6 @@
-::: opendal.Metadata
+::: opendal.Capability
     options:
-      heading: "opendal.Metadata"
+      heading: "opendal.Capability"
       heading_level: 2
       show_source: false
       show_bases: false

bindings/python/docs/api/exceptions.md

@@ -0,0 +1,45 @@
+This page documents all exceptions raised by the OpenDAL.
+
+::: opendal.exceptions.Error
+    options:
+      heading_level: 2
+
+::: opendal.exceptions.AlreadyExists
+    options:
+      heading_level: 2
+
+::: opendal.exceptions.ConditionNotMatch
+    options:
+      heading_level: 2
+
+::: opendal.exceptions.ConfigInvalid
+    options:
+      heading_level: 2
+
+::: opendal.exceptions.IsADirectory
+    options:
+      heading_level: 2
+
+::: opendal.exceptions.IsSameFile
+    options:
+      heading_level: 2
+
+::: opendal.exceptions.NotADirectory
+    options:
+      heading_level: 2
+
+::: opendal.exceptions.NotFound
+    options:
+      heading_level: 2
+
+::: opendal.exceptions.PermissionDenied
+    options:
+      heading_level: 2
+
+::: opendal.exceptions.Unexpected
+    options:
+      heading_level: 2
+
+::: opendal.exceptions.Unsupported
+    options:
+      heading_level: 2

bindings/python/docs/api/layers.md

@@ -0,0 +1,32 @@
+# Layers   
+
+This page documents all layers in OpenDAL.
+
+## Layer
+::: opendal.layers.Layer
+    options:
+      heading: "opendal.layers.Layer"
+      heading_level: 2
+      show_source: false
+      show_bases: false
+
+## RetryLayer   
+::: opendal.layers.RetryLayer
+    options:
+      heading: "opendal.layers.RetryLayer"
+      heading_level: 2
+      show_source: false
+
+## ConcurrentLimitLayer   
+::: opendal.layers.ConcurrentLimitLayer
+    options:
+      heading: "opendal.layers.ConcurrentLimitLayer"
+      heading_level: 2
+      show_source: false
+
+## MimeGuessLayer   
+::: opendal.layers.MimeGuessLayer
+    options:
+      heading: "opendal.layers.MimeGuessLayer"
+      heading_level: 2
+      show_source: false

bindings/python/docs/api/types.md

@@ -0,0 +1,25 @@
+# Types   
+
+This page documents all types in OpenDAL.
+
+## Entry
+::: opendal.Entry
+    options:
+      heading: "opendal.Entry"
+      heading_level: 2
+      show_source: false
+      show_bases: false
+
+## EntryMode   
+::: opendal.types.EntryMode
+    options:
+      heading: "opendal.EntryMode"
+      heading_level: 2
+
+## Metadata   
+::: opendal.types.Metadata
+    options:
+      heading: "opendal.Metadata"
+      heading_level: 2
+      show_source: false
+      show_bases: false

bindings/python/mkdocs.yml

@@ -43,11 +43,14 @@ nav:
       - Pandas: examples/pandas.ipynb
       - Polars: examples/polars.ipynb
   - API Reference:
-      - api/operator.md
-      - api/file.md
-      - api/async_operator.md
-      - api/async_file.md
-      - api/metadata.md
+      - AsyncFile: api/async_file.md
+      - AsyncOperator: api/async_operator.md
+      - Capability: api/capability.md
+      - Exceptions: api/exceptions.md
+      - File: api/file.md
+      - Layers: api/layers.md
+      - Operator: api/operator.md
+      - Types: api/types.md
 
 markdown_extensions:
   - pymdownx.highlight:

bindings/python/pyrightconfig.json

@@ -0,0 +1,6 @@
+{
+  "include": ["python/opendal/"],
+  "ignore": [
+    "python/opendal/*.pyi"
+  ]
+}

bindings/python/python/opendal/__init__.pyi

@@ -17,7 +17,6 @@
 
 import os
 from collections.abc import AsyncIterable, Iterable
-from datetime import datetime
 from types import TracebackType
 from typing import TypeAlias, final
 
@@ -30,6 +29,7 @@ from opendal import layers as layers
 from opendal.__base import _Base
 from opendal.capability import Capability
 from opendal.layers import Layer
+from opendal.types import Entry, Metadata
 
 PathBuf: TypeAlias = str | os.PathLike
 
@@ -703,61 +703,6 @@ class AsyncFile:
     async def writable(self) -> bool:
         """Check if the file is writable."""
 
-@final
-class Entry:
-    """An entry in the directory listing."""
-
-    @property
-    def path(self) -> str:
-        """The path of the entry."""
-    @property
-    def metadata(self) -> Metadata:
-        """The metadata of the entry."""
-
-@final
-class Metadata:
-    @property
-    def content_disposition(self) -> str | None:
-        """The content disposition of the object."""
-    @property
-    def content_length(self) -> int:
-        """The content length of the object."""
-    @property
-    def content_md5(self) -> str | None:
-        """The MD5 checksum of the object."""
-    @property
-    def content_type(self) -> str | None:
-        """The mime type of the object."""
-    @property
-    def content_encoding(self) -> str | None:
-        """The content encoding of the object."""
-    @property
-    def etag(self) -> str | None:
-        """The ETag of the object."""
-    @property
-    def mode(self) -> EntryMode:
-        """The mode of the object."""
-    @property
-    def is_file(self) -> bool:
-        """Returns `True` if this metadata is for a file."""
-    @property
-    def is_dir(self) -> bool:
-        """Returns `True` if this metadata is for a directory."""
-    @property
-    def last_modified(self) -> datetime | None:
-        """The last modified time of the object."""
-    @property
-    def version(self) -> str | None:
-        """The version of the object, if available."""
-    @property
-    def user_metadata(self) -> str | None:
-        """The user defined metadata of the object."""
-
-@final
-class EntryMode:
-    def is_file(self) -> bool: ...
-    def is_dir(self) -> bool: ...
-
 @final
 class PresignedRequest:
     @property

bindings/python/python/opendal/layers.pyi

@@ -15,25 +15,122 @@
 # specific language governing permissions and limitations
 # under the License.
 
-from typing import final
+# This file is automatically generated by pyo3_stub_gen
+# ruff: noqa: E501, F401
 
-class Layer: ...
+import builtins
+import typing
 
-@final
-class RetryLayer(Layer):
-    def __init__(
-        self,
-        max_times: int | None = None,
-        factor: float | None = None,
-        jitter: bool = False,
-        max_delay: float | None = None,
-        min_delay: float | None = None,
-    ) -> None: ...
-
-@final
+@typing.final
 class ConcurrentLimitLayer(Layer):
-    def __init__(self, limit: int) -> None: ...
+    r"""
+    ConcurrentLimitLayer.
+
+    Create a layer that limits the number of concurrent operations.
+
+    Notes
+    -----
+    All operators wrapped by this layer will share a common semaphore. This
+    allows you to reuse the same layer across multiple operators, ensuring
+    that the total number of concurrent requests across the entire
+    application does not exceed the limit.
+    """
+
+    def __new__(cls, limit: builtins.int) -> ConcurrentLimitLayer:
+        r"""
+        Create a new ConcurrentLimitLayer.
+
+        Parameters
+        ----------
+        limit : int
+            Maximum number of concurrent operations allowed.
+
+        Returns
+        -------
+        ConcurrentLimitLayer
+        """
 
-@final
+class Layer:
+    r"""
+    Layer.
+
+    Layers are used to intercept the operations on the underlying storage.
+    """
+
+@typing.final
 class MimeGuessLayer(Layer):
-    def __init__(self) -> None: ...
+    r"""
+    MimeGuessLayer.
+
+    Create a layer that guesses MIME types for objects based on their
+    paths or content.
+
+    This layer uses the `mime_guess` crate
+    (see https://crates.io/crates/mime_guess) to infer the
+    ``Content-Type``.
+
+    Notes
+    -----
+    This layer will not override a ``Content-Type`` that has already
+    been set, either manually or by the backend service. It is only
+    applied if no content type is present.
+
+    A ``Content-Type`` is not guaranteed. If the file extension is
+    uncommon or unknown, the content type will remain unset.
+    """
+
+    def __new__(cls) -> MimeGuessLayer:
+        r"""
+        Create a new MimeGuessLayer.
+
+        Returns
+        -------
+        MimeGuessLayer
+        """
+
+@typing.final
+class RetryLayer(Layer):
+    r"""
+    RetryLayer.
+
+    A layer that retries operations that fail with temporary errors.
+
+    Operations are retried if they fail with an error for which
+    `Error.is_temporary` returns `True`. If all retries are exhausted,
+    the error is marked as persistent and then returned.
+
+    Notes
+    -----
+    After an operation on a `Reader` or `Writer` has failed through
+    all retries, the object is in an undefined state. Reusing it
+    can lead to exceptions.
+    """
+
+    def __new__(
+        cls,
+        max_times: builtins.int | None = None,
+        factor: builtins.float | None = None,
+        jitter: builtins.bool = False,
+        max_delay: builtins.float | None = None,
+        min_delay: builtins.float | None = None,
+    ) -> RetryLayer:
+        r"""
+        Create a new RetryLayer.
+
+        Parameters
+        ----------
+        max_times : Optional[int]
+            Maximum number of retry attempts. Defaults to ``3``.
+        factor : Optional[float]
+            Backoff factor applied between retries. Defaults to ``2.0``.
+        jitter : bool
+            Whether to apply jitter to the backoff. Defaults to ``False``.
+        max_delay : Optional[float]
+            Maximum delay (in seconds) between retries. Defaults to ``60.0``.
+        min_delay : Optional[float]
+            Minimum delay (in seconds) between retries. Defaults to ``1.0``.
+
+        Returns
+        -------
+        RetryLayer
+        """