Issue 1028: public delete functions for run, task, flow and database (#…

…1060)
openml · mfeurer · Mar 22, 2023 · May 31, 2021 · Jun 16, 2021 · Oct 27, 2021
commit 3c00d7b05b17d248d53db40d1b437808f86e1442
diff --git a/.gitignore b/.gitignore
@@ -77,6 +77,7 @@ target/
 # IDE
 .idea
 *.swp
+.vscode
 
 # MYPY
 .mypy_cache

diff --git a/doc/api.rst b/doc/api.rst
@@ -38,6 +38,7 @@ Dataset Functions
     attributes_arff_from_df
     check_datasets_active
     create_dataset
+    delete_dataset
     get_dataset
     get_datasets
     list_datasets
@@ -103,6 +104,7 @@ Flow Functions
    :template: function.rst
 
     assert_flows_equal
+    delete_flow
     flow_exists
     get_flow
     list_flows
@@ -133,6 +135,7 @@ Run Functions
    :toctree: generated/
    :template: function.rst
 
+    delete_run
     get_run
     get_runs
     get_run_trace
@@ -251,6 +254,7 @@ Task Functions
    :template: function.rst
 
     create_task
+    delete_task
     get_task
     get_tasks
     list_tasks

diff --git a/doc/progress.rst b/doc/progress.rst
@@ -10,10 +10,10 @@ Changelog
 ~~~~~~
 
  * Add new contributions here.
- * ADD#1144: Add locally computed results to the ``OpenMLRun`` object's representation.
+ * ADD#1028: Add functions to delete runs, flows, datasets, and tasks (e.g., ``openml.datasets.delete_dataset``).
+ * ADD#1144: Add locally computed results to the ``OpenMLRun`` object's representation if the run was created locally and not downloaded from the server.
  * FIX #1197 #559 #1131: Fix the order of ground truth and predictions in the ``OpenMLRun`` object and in ``format_prediction``.
  * FIX #1198: Support numpy 1.24 and higher.
- * ADD#1144: Add locally computed results to the ``OpenMLRun`` object's representation if the run was created locally and not downloaded from the server.
 
 0.13.0
 ~~~~~~

diff --git a/openml/_api_calls.py b/openml/_api_calls.py
@@ -351,10 +351,12 @@ def _send_request(request_method, url, data, files=None, md5_checksum=None):
                 xml.parsers.expat.ExpatError,
                 OpenMLHashException,
             ) as e:
-                if isinstance(e, OpenMLServerException):
-                    if e.code not in [107]:
-                        # 107: database connection error
-                        raise
+                if isinstance(e, OpenMLServerException) and e.code != 107:
+                    # Propagate all server errors to the calling functions, except
+                    # for 107 which represents a database connection error.
+                    # These are typically caused by high server load,
+                    # which means trying again might resolve the issue.
+                    raise
                 elif isinstance(e, xml.parsers.expat.ExpatError):
                     if request_method != "get" or retry_counter >= n_retries:
                         raise OpenMLServerError(

diff --git a/openml/datasets/__init__.py b/openml/datasets/__init__.py
@@ -11,6 +11,7 @@
     list_qualities,
     edit_dataset,
     fork_dataset,
+    delete_dataset,
 )
 from .dataset import OpenMLDataset
 from .data_feature import OpenMLDataFeature
@@ -28,4 +29,5 @@
     "list_qualities",
     "edit_dataset",
     "fork_dataset",
+    "delete_dataset",
 ]
diff --git a/openml/datasets/functions.py b/openml/datasets/functions.py
@@ -1271,3 +1271,22 @@ def _get_online_dataset_format(dataset_id):
     dataset_xml = openml._api_calls._perform_api_call("data/%d" % dataset_id, "get")
     # build a dict from the xml and get the format from the dataset description
     return xmltodict.parse(dataset_xml)["oml:data_set_description"]["oml:format"].lower()
+
+
+def delete_dataset(dataset_id: int) -> bool:
+    """Delete dataset with id `dataset_id` from the OpenML server.
+
+    This can only be done if you are the owner of the dataset and
+    no tasks are attached to the dataset.
+
+    Parameters
+    ----------
+    dataset_id : int
+        OpenML id of the dataset
+
+    Returns
+    -------
+    bool
+        True if the deletion was successful. False otherwise.
+    """
+    return openml.utils._delete_entity("data", dataset_id)
diff --git a/openml/exceptions.py b/openml/exceptions.py
@@ -11,15 +11,14 @@ class OpenMLServerError(PyOpenMLError):
     """class for when something is really wrong on the server
     (result did not parse to dict), contains unparsed error."""
 
-    def __init__(self, message: str):
-        super().__init__(message)
+    pass
 
 
 class OpenMLServerException(OpenMLServerError):
     """exception for when the result of the server was
     not 200 (e.g., listing call w/o results)."""
 
-    # Code needs to be optional to allow the exceptino to be picklable:
+    # Code needs to be optional to allow the exception to be picklable:
     # https://stackoverflow.com/questions/16244923/how-to-make-a-custom-exception-class-with-multiple-init-args-pickleable  # noqa: E501
     def __init__(self, message: str, code: int = None, url: str = None):
         self.message = message
@@ -28,24 +27,19 @@ def __init__(self, message: str, code: int = None, url: str = None):
         super().__init__(message)
 
     def __str__(self):
-        return "%s returned code %s: %s" % (
-            self.url,
-            self.code,
-            self.message,
-        )
+        return f"{self.url} returned code {self.code}: {self.message}"
 
 
 class OpenMLServerNoResult(OpenMLServerException):
-    """exception for when the result of the server is empty."""
+    """Exception for when the result of the server is empty."""
 
     pass
 
 
 class OpenMLCacheException(PyOpenMLError):
     """Dataset / task etc not found in cache"""
 
-    def __init__(self, message: str):
-        super().__init__(message)
+    pass
 
 
 class OpenMLHashException(PyOpenMLError):
@@ -57,8 +51,7 @@ class OpenMLHashException(PyOpenMLError):
 class OpenMLPrivateDatasetError(PyOpenMLError):
     """Exception thrown when the user has no rights to access the dataset."""
 
-    def __init__(self, message: str):
-        super().__init__(message)
+    pass
 
 
 class OpenMLRunsExistError(PyOpenMLError):
@@ -69,3 +62,9 @@ def __init__(self, run_ids: set, message: str):
             raise ValueError("Set of run ids must be non-empty.")
         self.run_ids = run_ids
         super().__init__(message)
+
+
+class OpenMLNotAuthorizedError(OpenMLServerError):
+    """Indicates an authenticated user is not authorized to execute the requested action."""
+
+    pass
diff --git a/openml/flows/__init__.py b/openml/flows/__init__.py
@@ -2,7 +2,14 @@
 
 from .flow import OpenMLFlow
 
-from .functions import get_flow, list_flows, flow_exists, get_flow_id, assert_flows_equal
+from .functions import (
+    get_flow,
+    list_flows,
+    flow_exists,
+    get_flow_id,
+    assert_flows_equal,
+    delete_flow,
+)
 
 __all__ = [
     "OpenMLFlow",
@@ -11,4 +18,5 @@
     "get_flow_id",
     "flow_exists",
     "assert_flows_equal",
+    "delete_flow",
 ]
diff --git a/openml/flows/functions.py b/openml/flows/functions.py
@@ -544,3 +544,22 @@ def _create_flow_from_xml(flow_xml: str) -> OpenMLFlow:
     """
 
     return OpenMLFlow._from_dict(xmltodict.parse(flow_xml))
+
+
+def delete_flow(flow_id: int) -> bool:
+    """Delete flow with id `flow_id` from the OpenML server.
+
+    You can only delete flows which you uploaded and which
+    which are not linked to runs.
+
+    Parameters
+    ----------
+    flow_id : int
+        OpenML id of the flow
+
+    Returns
+    -------
+    bool
+        True if the deletion was successful. False otherwise.
+    """
+    return openml.utils._delete_entity("flow", flow_id)
diff --git a/openml/runs/__init__.py b/openml/runs/__init__.py
@@ -12,6 +12,7 @@
     run_exists,
     initialize_model_from_run,
     initialize_model_from_trace,
+    delete_run,
 )
 
 __all__ = [
@@ -27,4 +28,5 @@
     "run_exists",
     "initialize_model_from_run",
     "initialize_model_from_trace",
+    "delete_run",
 ]
diff --git a/openml/runs/functions.py b/openml/runs/functions.py
@@ -1209,3 +1209,21 @@ def format_prediction(
         return [repeat, fold, index, prediction, truth]
     else:
         raise NotImplementedError(f"Formatting for {type(task)} is not supported.")
+
+
+def delete_run(run_id: int) -> bool:
+    """Delete run with id `run_id` from the OpenML server.
+
+    You can only delete runs which you uploaded.
+
+    Parameters
+    ----------
+    run_id : int
+        OpenML id of the run
+
+    Returns
+    -------
+    bool
+        True if the deletion was successful. False otherwise.
+    """
+    return openml.utils._delete_entity("run", run_id)
diff --git a/openml/tasks/__init__.py b/openml/tasks/__init__.py
@@ -15,6 +15,7 @@
     get_task,
     get_tasks,
     list_tasks,
+    delete_task,
 )
 
 __all__ = [
@@ -30,4 +31,5 @@
     "list_tasks",
     "OpenMLSplit",
     "TaskType",
+    "delete_task",
 ]
diff --git a/openml/tasks/functions.py b/openml/tasks/functions.py
@@ -545,3 +545,22 @@ def create_task(
             evaluation_measure=evaluation_measure,
             **kwargs,
         )
+
+
+def delete_task(task_id: int) -> bool:
+    """Delete task with id `task_id` from the OpenML server.
+
+    You can only delete tasks which you created and have
+    no runs associated with them.
+
+    Parameters
+    ----------
+    task_id : int
+        OpenML id of the task
+
+    Returns
+    -------
+    bool
+        True if the deletion was successful. False otherwise.
+    """
+    return openml.utils._delete_entity("task", task_id)
diff --git a/openml/testing.py b/openml/testing.py
@@ -3,12 +3,14 @@
 import hashlib
 import inspect
 import os
+import pathlib
 import shutil
 import sys
 import time
 from typing import Dict, Union, cast
 import unittest
 import pandas as pd
+import requests
 
 import openml
 from openml.tasks import TaskType
@@ -306,4 +308,22 @@ class CustomImputer(SimpleImputer):
     pass
 
 
-__all__ = ["TestBase", "SimpleImputer", "CustomImputer", "check_task_existence"]
+def create_request_response(
+    *, status_code: int, content_filepath: pathlib.Path
+) -> requests.Response:
+    with open(content_filepath, "r") as xml_response:
+        response_body = xml_response.read()
+
+    response = requests.Response()
+    response.status_code = status_code
+    response._content = response_body.encode()
+    return response
+
+
+__all__ = [
+    "TestBase",
+    "SimpleImputer",
+    "CustomImputer",
+    "check_task_existence",
+    "create_request_response",
+]
diff --git a/openml/utils.py b/openml/utils.py
@@ -172,9 +172,42 @@ def _delete_entity(entity_type, entity_id):
         raise ValueError("Can't delete a %s" % entity_type)
 
     url_suffix = "%s/%d" % (entity_type, entity_id)
-    result_xml = openml._api_calls._perform_api_call(url_suffix, "delete")
-    result = xmltodict.parse(result_xml)
-    return "oml:%s_delete" % entity_type in result
+    try:
+        result_xml = openml._api_calls._perform_api_call(url_suffix, "delete")
+        result = xmltodict.parse(result_xml)
+        return f"oml:{entity_type}_delete" in result
+    except openml.exceptions.OpenMLServerException as e:
+        # https://github.com/openml/OpenML/blob/21f6188d08ac24fcd2df06ab94cf421c946971b0/openml_OS/views/pages/api_new/v1/xml/pre.php
+        # Most exceptions are descriptive enough to be raised as their standard
+        # OpenMLServerException, however there are two cases where we add information:
+        #  - a generic "failed" message, we direct them to the right issue board
+        #  - when the user successfully authenticates with the server,
+        #    but user is not allowed to take the requested action,
+        #    in which case we specify a OpenMLNotAuthorizedError.
+        by_other_user = [323, 353, 393, 453, 594]
+        has_dependent_entities = [324, 326, 327, 328, 354, 454, 464, 595]
+        unknown_reason = [325, 355, 394, 455, 593]
+        if e.code in by_other_user:
+            raise openml.exceptions.OpenMLNotAuthorizedError(
+                message=(
+                    f"The {entity_type} can not be deleted because it was not uploaded by you."
+                ),
+            ) from e
+        if e.code in has_dependent_entities:
+            raise openml.exceptions.OpenMLNotAuthorizedError(
+                message=(
+                    f"The {entity_type} can not be deleted because "
+                    f"it still has associated entities: {e.message}"
+                )
+            ) from e
+        if e.code in unknown_reason:
+            raise openml.exceptions.OpenMLServerError(
+                message=(
+                    f"The {entity_type} can not be deleted for unknown reason,"
+                    " please open an issue at: https://github.com/openml/openml/issues/new"
+                ),
+            ) from e
+        raise
 
 
 def _list_all(listing_call, output_format="dict", *args, **filters):

diff --git a/tests/conftest.py b/tests/conftest.py
@@ -185,3 +185,13 @@ def pytest_addoption(parser):
 @pytest.fixture(scope="class")
 def long_version(request):
     request.cls.long_version = request.config.getoption("--long")
+
+
+@pytest.fixture
+def test_files_directory() -> pathlib.Path:
+    return pathlib.Path(__file__).parent / "files"
+
+
+@pytest.fixture()
+def test_api_key() -> str:
+    return "c0c42819af31e706efe1f4b88c23c6c1"
diff --git a/tests/files/mock_responses/datasets/data_delete_has_tasks.xml b/tests/files/mock_responses/datasets/data_delete_has_tasks.xml
@@ -0,0 +1,4 @@
+<oml:error xmlns:oml="http://openml.org/openml">
+	<oml:code>354</oml:code>
+	<oml:message>Dataset is in use by other content. Can not be deleted</oml:message>
+</oml:error>
diff --git a/tests/files/mock_responses/datasets/data_delete_not_exist.xml b/tests/files/mock_responses/datasets/data_delete_not_exist.xml
@@ -0,0 +1,4 @@
+<oml:error xmlns:oml="http://openml.org/openml">
+	<oml:code>352</oml:code>
+	<oml:message>Dataset does not exist</oml:message>
+</oml:error>
-Original file line number
+Diff line change
@@ Expand Up / @@ -77,6 +77,7 @@ target/ @@
     # IDE
     .idea
     *.swp
+    .vscode
     # MYPY
     .mypy_cache
@@ Expand Down @@