Merge branch 'main' into docs-for-get-publish

Author: geetu040

CONTRIBUTING.md

@@ -107,6 +107,32 @@ $env:OPENML_TEST_SERVER_ADMIN_KEY = "admin-key"
 export OPENML_TEST_SERVER_ADMIN_KEY="admin-key"
 ```
 
+#### Diagnosing Slow Tests
+
+If you suspect a test (or the suite as a whole) is running too slowly, `pytest` already exposes everything you need to investigate it. A few invocations that are useful when looking into test runtimes:
+
+```bash
+# Show the 20 slowest tests (use 0 to list every test's duration)
+pytest tests --durations=20
+
+# Fail any test that exceeds the given timeout (requires pytest-timeout)
+pytest tests --timeout=600
+
+# Investigate only fixture/setup costs without actually running the tests
+pytest tests --setup-only
+
+# Profile a specific module, class, or test
+pytest tests/test_datasets/test_dataset.py --durations=0
+
+# Skip the slow live-server tests while profiling locally
+pytest tests --durations=0 -m "not production_server and not test_server"
+
+# Run the suite in parallel to reproduce CI behaviour (requires pytest-xdist)
+pytest tests -n 4 --dist=load --durations=0
+```
+
+Combining these with the marker filters (`production_server`, `test_server`, `sklearn`) makes it straightforward to narrow the investigation down to the slow tests without changing project configuration.
+
 ### Pull Request Checklist
 
 You can go to the `openml-python` GitHub repository to create the pull request by [comparing the branch](https://github.com/openml/openml-python/compare) from your fork with the `main` branch of the `openml-python` repository. When creating a pull request, make sure to follow the comments and structured provided by the template on GitHub.
@@ -214,4 +240,4 @@ When dependencies are installed, run
 ```bash
 mkdocs serve
 ```
-This will open a preview of the website.
+This will open a preview of the website.

openml/_api/resources/base/resources.py

@@ -10,6 +10,8 @@
 from .base import ResourceAPI
 
 if TYPE_CHECKING:
+    import pandas as pd
+
     from openml.estimation_procedures import OpenMLEstimationProcedure
     from openml.evaluations import OpenMLEvaluation
     from openml.flows.flow import OpenMLFlow
@@ -80,6 +82,17 @@ class StudyAPI(ResourceAPI):
 
     resource_type: ResourceType = ResourceType.STUDY
 
+    @abstractmethod
+    def list(  # noqa: PLR0913
+        self,
+        limit: int | None = None,
+        offset: int | None = None,
+        status: str | None = None,
+        main_entity_type: str | None = None,
+        uploader: list[int] | None = None,
+        benchmark_suite: int | None = None,
+    ) -> pd.DataFrame: ...
+
 
 class RunAPI(ResourceAPI):
     """Abstract API interface for run resources."""

openml/_api/resources/base/versions.py

@@ -25,6 +25,7 @@
     ResourceType.DATASET,
     ResourceType.TASK,
     ResourceType.FLOW,
+    ResourceType.STUDY,
     ResourceType.SETUP,
     ResourceType.RUN,
 ]

openml/_api/resources/study.py

@@ -1,11 +1,162 @@
 from __future__ import annotations
 
-from .base import ResourceV1API, ResourceV2API, StudyAPI
+import builtins
+
+import pandas as pd
+import xmltodict
+
+from openml._api.resources.base import ResourceV1API, ResourceV2API, StudyAPI
 
 
 class StudyV1API(ResourceV1API, StudyAPI):
-    """Version 1 API implementation for study resources."""
+    def list(  # noqa: PLR0913
+        self,
+        limit: int | None = None,
+        offset: int | None = None,
+        status: str | None = None,
+        main_entity_type: str | None = None,
+        uploader: builtins.list[int] | None = None,
+        benchmark_suite: int | None = None,
+    ) -> pd.DataFrame:
+        """List studies using V1 API.
+
+        Parameters
+        ----------
+        limit : int, optional
+            Maximum number of studies to return.
+        offset : int, optional
+            Number of studies to skip.
+        status : str, optional
+            Filter by status (active, in_preparation, deactivated, all).
+        main_entity_type : str, optional
+            Filter by main entity type (run, task).
+        uploader : list[int], optional
+            Filter by uploader IDs.
+        benchmark_suite : int, optional
+            Filter by benchmark suite ID.
+
+        Returns
+        -------
+        pd.DataFrame
+            DataFrame containing study information.
+        """
+        api_call = self._build_url(
+            limit=limit,
+            offset=offset,
+            status=status,
+            main_entity_type=main_entity_type,
+            uploader=uploader,
+            benchmark_suite=benchmark_suite,
+        )
+        response = self._http.get(api_call)
+        xml_string = response.content.decode("utf-8")
+        return self._parse_list_xml(xml_string)
+
+    @staticmethod
+    def _build_url(  # noqa: PLR0913
+        limit: int | None = None,
+        offset: int | None = None,
+        status: str | None = None,
+        main_entity_type: str | None = None,
+        uploader: builtins.list[int] | None = None,
+        benchmark_suite: int | None = None,
+    ) -> str:
+        """Build the V1 API URL for listing studies.
+
+        Parameters
+        ----------
+        limit : int, optional
+            Maximum number of studies to return.
+        offset : int, optional
+            Number of studies to skip.
+        status : str, optional
+            Filter by status (active, in_preparation, deactivated, all).
+        main_entity_type : str, optional
+            Filter by main entity type (run, task).
+        uploader : list[int], optional
+            Filter by uploader IDs.
+        benchmark_suite : int, optional
+            Filter by benchmark suite ID.
+
+        Returns
+        -------
+        str
+            The API call string with all filters applied.
+        """
+        api_call = "study/list"
+
+        if limit is not None:
+            api_call += f"/limit/{limit}"
+        if offset is not None:
+            api_call += f"/offset/{offset}"
+        if status is not None:
+            api_call += f"/status/{status}"
+        if main_entity_type is not None:
+            api_call += f"/main_entity_type/{main_entity_type}"
+        if uploader is not None:
+            api_call += f"/uploader/{','.join(str(u) for u in uploader)}"
+        if benchmark_suite is not None:
+            api_call += f"/benchmark_suite/{benchmark_suite}"
+
+        return api_call
+
+    @staticmethod
+    def _parse_list_xml(xml_string: str) -> pd.DataFrame:
+        """Parse the XML response from study list API.
+
+        Parameters
+        ----------
+        xml_string : str
+            The XML response from the API.
+
+        Returns
+        -------
+        pd.DataFrame
+            DataFrame containing study information.
+        """
+        study_dict = xmltodict.parse(xml_string, force_list=("oml:study",))
+
+        # Minimalistic check if the XML is useful
+        assert isinstance(study_dict["oml:study_list"]["oml:study"], list), type(
+            study_dict["oml:study_list"],
+        )
+        assert study_dict["oml:study_list"]["@xmlns:oml"] == "http://openml.org/openml", study_dict[
+            "oml:study_list"
+        ]["@xmlns:oml"]
+
+        studies = {}
+        for study_ in study_dict["oml:study_list"]["oml:study"]:
+            # maps from xml name to a tuple of (dict name, casting fn)
+            expected_fields = {
+                "oml:id": ("id", int),
+                "oml:alias": ("alias", str),
+                "oml:main_entity_type": ("main_entity_type", str),
+                "oml:benchmark_suite": ("benchmark_suite", int),
+                "oml:name": ("name", str),
+                "oml:status": ("status", str),
+                "oml:creation_date": ("creation_date", str),
+                "oml:creator": ("creator", int),
+            }
+            study_id = int(study_["oml:id"])
+            current_study = {}
+            for oml_field_name, (real_field_name, cast_fn) in expected_fields.items():
+                if oml_field_name in study_:
+                    current_study[real_field_name] = cast_fn(study_[oml_field_name])
+            current_study["id"] = int(current_study["id"])
+            studies[study_id] = current_study
+
+        return pd.DataFrame.from_dict(studies, orient="index")
 
 
 class StudyV2API(ResourceV2API, StudyAPI):
-    """Version 2 API implementation for study resources."""
+    def list(  # noqa: PLR0913
+        self,
+        limit: int | None = None,  # noqa: ARG002
+        offset: int | None = None,  # noqa: ARG002
+        status: str | None = None,  # noqa: ARG002
+        main_entity_type: str | None = None,  # noqa: ARG002
+        uploader: builtins.list[int] | None = None,  # noqa: ARG002
+        benchmark_suite: int | None = None,  # noqa: ARG002
+    ) -> pd.DataFrame:
+        """V2 API for listing studies is not yet available."""
+        self._not_supported(method="list")

openml/datasets/functions.py

@@ -364,6 +364,11 @@ def get_datasets(
     -------
     datasets : list of datasets
         A list of dataset objects.
+
+    Examples
+    --------
+    >>> import openml
+    >>> datasets = openml.datasets.get_datasets([1, 2, 3])  # doctest: +SKIP
     """
     datasets = []
     for dataset_id in dataset_ids:
@@ -446,6 +451,13 @@ def get_dataset(  # noqa: C901, PLR0912
     -------
     dataset : :class:`openml.OpenMLDataset`
         The downloaded dataset.
+
+    Examples
+    --------
+    >>> import openml
+    >>> dataset = openml.datasets.get_dataset(1)  # doctest: +SKIP
+    >>> dataset = openml.datasets.get_dataset("iris", version=1)  # doctest: +SKIP
+    >>> dataset = openml.datasets.get_dataset(1, download_data=True)  # doctest: +SKIP
     """
     if download_all_files:
         warnings.warn(

openml/runs/functions.py

@@ -103,6 +103,15 @@ def run_model_on_task(  # noqa: PLR0913
         Result of the run.
     flow : OpenMLFlow (optional, only if `return_flow` is True).
         Flow generated from the model.
+
+    Examples
+    --------
+    >>> import openml
+    >>> import openml_sklearn  # doctest: +SKIP
+    >>> from sklearn.tree import DecisionTreeClassifier  # doctest: +SKIP
+    >>> clf = DecisionTreeClassifier()  # doctest: +SKIP
+    >>> task = openml.tasks.get_task(6)  # doctest: +SKIP
+    >>> run = openml.runs.run_model_on_task(clf, task)  # doctest: +SKIP
     """
     if avoid_duplicate_runs is None:
         avoid_duplicate_runs = openml.config.avoid_duplicate_runs
@@ -558,9 +567,14 @@ def _run_task_get_arffcontent(  # noqa: PLR0915, PLR0912, C901
     )  # job_rvals contain the output of all the runs with one-to-one correspondence with `jobs`
 
     for n_fit, rep_no, fold_no, sample_no in jobs:
-        pred_y, proba_y, test_indices, test_y, inner_trace, user_defined_measures_fold = job_rvals[
-            n_fit - 1
-        ]
+        (
+            pred_y,
+            proba_y,
+            test_indices,
+            test_y,
+            inner_trace,
+            user_defined_measures_fold,
+        ) = job_rvals[n_fit - 1]
 
         if inner_trace is not None:
             traces.append(inner_trace)
@@ -845,7 +859,10 @@ def get_run(run_id: int, ignore_cache: bool = False) -> OpenMLRun:  # noqa: FBT0
     return _create_run_from_xml(run_xml)
 
 
-def _create_run_from_xml(xml: str, from_server: bool = True) -> OpenMLRun:  # noqa: PLR0915, PLR0912, C901, FBT002
+def _create_run_from_xml(  # noqa: PLR0915, PLR0912, C901
+    xml: str,
+    from_server: bool = True,  # noqa: FBT002
+) -> OpenMLRun:
     """Create a run object from xml returned from server.
 
     Parameters