merge

Author: Omswastik-11

openml/_api/clients/http.py

@@ -6,6 +6,29 @@
 
 
 class MinIOClient:
-    def __init__(self, path: Path | None = None) -> None:
+    """
+    Lightweight client configuration for interacting with a MinIO-compatible
+    object storage service.
+
+    This class stores basic configuration such as a base filesystem path and
+    default HTTP headers. It is intended to be extended with actual request
+    or storage logic elsewhere.
+
+    Parameters
+    ----------
+    path : pathlib.Path or None, optional
+        Base path used for local storage or downloads. If ``None``, no
+        default path is configured.
+
+    Attributes
+    ----------
+    path : pathlib.Path or None
+        Configured base path for storage operations.
+    headers : dict of str to str
+        Default HTTP headers, including a user-agent identifying the
+        OpenML Python client version.
+    """
+
+    def __init__(self, path: Path) -> None:
         self.path = path
         self.headers: dict[str, str] = {"user-agent": f"openml-python/{__version__}"}

openml/_api/clients/minio.py

@@ -42,12 +42,10 @@
     "EvaluationV1API",
     "EvaluationV2API",
     "FallbackProxy",
-    "FallbackProxy",
     "FlowAPI",
     "FlowV1API",
     "FlowV2API",
     "ResourceAPI",
-    "ResourceAPI",
     "ResourceV1API",
     "ResourceV2API",
     "RunAPI",

openml/_api/resources/__init__.py

@@ -14,6 +14,33 @@
 
 
 class ResourceAPI(ABC):
+    """
+    Abstract base class for OpenML resource APIs.
+
+    This class defines the common interface for interacting with OpenML
+    resources (e.g., datasets, flows, runs) across different API versions.
+    Concrete subclasses must implement the resource-specific operations
+    such as publishing, deleting, and tagging.
+
+    Parameters
+    ----------
+    http : HTTPClient
+        Configured HTTP client used for communication with the OpenML API.
+    minio : MinIOClient or None, optional
+        Optional MinIO client used for object storage operations.
+
+    Attributes
+    ----------
+    api_version : APIVersion
+        API version implemented by the resource.
+    resource_type : ResourceType
+        Type of OpenML resource handled by the implementation.
+    _http : HTTPClient
+        Internal HTTP client instance.
+    _minio : MinIOClient or None
+        Internal MinIO client instance, if provided.
+    """
+
     api_version: APIVersion
     resource_type: ResourceType
 
@@ -22,18 +49,107 @@ def __init__(self, http: HTTPClient, minio: MinIOClient | None = None):
         self._minio = minio
 
     @abstractmethod
-    def delete(self, resource_id: int) -> bool: ...
+    def delete(self, resource_id: int) -> bool:
+        """
+        Delete a resource by its identifier.
+
+        Parameters
+        ----------
+        resource_id : int
+            Unique identifier of the resource to delete.
+
+        Returns
+        -------
+        bool
+            ``True`` if the deletion was successful.
+
+        Notes
+        -----
+        Concrete subclasses must implement this method.
+        """
 
     @abstractmethod
-    def publish(self, path: str, files: Mapping[str, Any] | None) -> int: ...
+    def publish(self, path: str, files: Mapping[str, Any] | None) -> int:
+        """
+        Publish a new resource to the OpenML server.
+
+        Parameters
+        ----------
+        path : str
+            API endpoint path used for publishing the resource.
+        files : Mapping of str to Any or None
+            Files or payload data required for publishing. The structure
+            depends on the resource type.
+
+        Returns
+        -------
+        int
+            Identifier of the newly created resource.
+
+        Notes
+        -----
+        Concrete subclasses must implement this method.
+        """
 
     @abstractmethod
-    def tag(self, resource_id: int, tag: str) -> list[str]: ...
+    def tag(self, resource_id: int, tag: str) -> list[str]:
+        """
+        Add a tag to a resource.
+
+        Parameters
+        ----------
+        resource_id : int
+            Identifier of the resource to tag.
+        tag : str
+            Tag to associate with the resource.
+
+        Returns
+        -------
+        list of str
+            Updated list of tags assigned to the resource.
+
+        Notes
+        -----
+        Concrete subclasses must implement this method.
+        """
 
     @abstractmethod
-    def untag(self, resource_id: int, tag: str) -> list[str]: ...
+    def untag(self, resource_id: int, tag: str) -> list[str]:
+        """
+        Remove a tag from a resource.
+
+        Parameters
+        ----------
+        resource_id : int
+            Identifier of the resource to untag.
+        tag : str
+            Tag to remove from the resource.
+
+        Returns
+        -------
+        list of str
+            Updated list of tags assigned to the resource.
+
+        Notes
+        -----
+        Concrete subclasses must implement this method.
+        """
 
     def _not_supported(self, *, method: str) -> NoReturn:
+        """
+        Raise an error indicating that a method is not supported.
+
+        Parameters
+        ----------
+        method : str
+            Name of the unsupported method.
+
+        Raises
+        ------
+        OpenMLNotSupportedError
+            If the current API version does not support the requested method
+            for the given resource type.
+        """
         version = getattr(self.api_version, "value", "unknown")
         resource = getattr(self.resource_type, "value", "unknown")
 

openml/_api/resources/base/base.py

@@ -7,18 +7,82 @@
 
 
 class FallbackProxy:
+    """
+    Proxy object that provides transparent fallback across multiple API versions.
+
+    This class delegates attribute access to a sequence of API implementations.
+    When a callable attribute is invoked and raises ``OpenMLNotSupportedError``,
+    the proxy automatically attempts the same method on subsequent API instances
+    until one succeeds.
+
+    Parameters
+    ----------
+    *api_versions : Any
+        One or more API implementation instances ordered by priority.
+        The first API is treated as the primary implementation, and
+        subsequent APIs are used as fallbacks.
+
+    Raises
+    ------
+    ValueError
+        If no API implementations are provided.
+
+    Notes
+    -----
+    Attribute lookup is performed dynamically via ``__getattr__``.
+    Only methods that raise ``OpenMLNotSupportedError`` trigger fallback
+    behavior. Other exceptions are propagated immediately.
+    """
+
     def __init__(self, *api_versions: Any):
         if not api_versions:
             raise ValueError("At least one API version must be provided")
         self._apis = api_versions
 
     def __getattr__(self, name: str) -> Any:
+        """
+        Dynamically resolve attribute access across API implementations.
+
+        Parameters
+        ----------
+        name : str
+            Name of the attribute being accessed.
+
+        Returns
+        -------
+        Any
+            The resolved attribute. If it is callable, a wrapped function
+            providing fallback behavior is returned.
+
+        Raises
+        ------
+        AttributeError
+            If none of the API implementations define the attribute.
+        """
         api, attr = self._find_attr(name)
         if callable(attr):
             return self._wrap_callable(name, api, attr)
         return attr
 
     def _find_attr(self, name: str) -> tuple[Any, Any]:
+        """
+        Find the first API implementation that defines a given attribute.
+
+        Parameters
+        ----------
+        name : str
+            Name of the attribute to search for.
+
+        Returns
+        -------
+        tuple of (Any, Any)
+            The API instance and the corresponding attribute.
+
+        Raises
+        ------
+        AttributeError
+            If no API implementation defines the attribute.
+        """
         for api in self._apis:
             attr = getattr(api, name, None)
             if attr is not None:
@@ -31,6 +95,25 @@ def _wrap_callable(
         primary_api: Any,
         primary_attr: Callable[..., Any],
     ) -> Callable[..., Any]:
+        """
+        Wrap a callable attribute to enable fallback behavior.
+
+        Parameters
+        ----------
+        name : str
+            Name of the method being wrapped.
+        primary_api : Any
+            Primary API instance providing the callable.
+        primary_attr : Callable[..., Any]
+            Callable attribute obtained from the primary API.
+
+        Returns
+        -------
+        Callable[..., Any]
+            Wrapped function that attempts the primary call first and
+            falls back to other APIs if ``OpenMLNotSupportedError`` is raised.
+        """
+
         def wrapper(*args: Any, **kwargs: Any) -> Any:
             try:
                 return primary_attr(*args, **kwargs)
@@ -46,6 +129,31 @@ def _call_fallbacks(
         *args: Any,
         **kwargs: Any,
     ) -> Any:
+        """
+        Attempt to call a method on fallback API implementations.
+
+        Parameters
+        ----------
+        name : str
+            Name of the method to invoke.
+        skip_api : Any
+            API instance to skip (typically the primary API that already failed).
+        *args : Any
+            Positional arguments passed to the method.
+        **kwargs : Any
+            Keyword arguments passed to the method.
+
+        Returns
+        -------
+        Any
+            Result returned by the first successful fallback invocation.
+
+        Raises
+        ------
+        OpenMLNotSupportedError
+            If all API implementations either do not define the method
+            or raise ``OpenMLNotSupportedError``.
+        """
         for api in self._apis:
             if api is skip_api:
                 continue

openml/_api/resources/base/fallback.py

@@ -16,34 +16,50 @@
 
 
 class DatasetAPI(ResourceAPI):
+    """Abstract API interface for dataset resources."""
+
     resource_type: ResourceType = ResourceType.DATASET
 
 
 class TaskAPI(ResourceAPI):
+    """Abstract API interface for task resources."""
+
     resource_type: ResourceType = ResourceType.TASK
 
 
 class EvaluationMeasureAPI(ResourceAPI):
+    """Abstract API interface for evaluation measure resources."""
+
     resource_type: ResourceType = ResourceType.EVALUATION_MEASURE
 
 
 class EstimationProcedureAPI(ResourceAPI):
+    """Abstract API interface for estimation procedure resources."""
+
     resource_type: ResourceType = ResourceType.ESTIMATION_PROCEDURE
 
 
 class EvaluationAPI(ResourceAPI):
+    """Abstract API interface for evaluation resources."""
+
     resource_type: ResourceType = ResourceType.EVALUATION
 
 
 class FlowAPI(ResourceAPI):
+    """Abstract API interface for flow resources."""
+
     resource_type: ResourceType = ResourceType.FLOW
 
 
 class StudyAPI(ResourceAPI):
+    """Abstract API interface for study resources."""
+
     resource_type: ResourceType = ResourceType.STUDY
 
 
 class RunAPI(ResourceAPI):
+    """Abstract API interface for run resources."""
+
     resource_type: ResourceType = ResourceType.RUN
 
     @abstractmethod
@@ -72,4 +88,6 @@ def list(  # type: ignore[valid-type]  # noqa: PLR0913
 
 
 class SetupAPI(ResourceAPI):
+    """Abstract API interface for setup resources."""
+
     resource_type: ResourceType = ResourceType.SETUP