_api

openml._api

APIBackend

Central backend for accessing all OpenML API resource interfaces.

This class provides a singleton interface to dataset, task, flow, evaluation, run, setup, study, and other resource APIs. It also manages configuration through a nested Config object and allows dynamic retrieval and updating of configuration values.

PARAMETER	DESCRIPTION
config	Optional configuration object. If not provided, a default Config instance is created. TYPE: Config

ATTRIBUTE	DESCRIPTION
dataset	Interface for dataset-related API operations. TYPE: DatasetAPI
task	Interface for task-related API operations. TYPE: TaskAPI
evaluation_measure	Interface for evaluation measure-related API operations. TYPE: EvaluationMeasureAPI
estimation_procedure	Interface for estimation procedure-related API operations. TYPE: EstimationProcedureAPI
evaluation	Interface for evaluation-related API operations. TYPE: EvaluationAPI
flow	Interface for flow-related API operations. TYPE: FlowAPI
study	Interface for study-related API operations. TYPE: StudyAPI
run	Interface for run-related API operations. TYPE: RunAPI
setup	Interface for setup-related API operations. TYPE: SetupAPI

get_instance classmethod

get_instance() -> APIBackend

Get the singleton instance of the APIBackend.

RETURNS	DESCRIPTION
APIBackend	Singleton instance of the backend.

Source code in openml/_api/setup/backend.py

@classmethod
def get_instance(cls) -> APIBackend:
    """
    Get the singleton instance of the APIBackend.

    Returns
    -------
    APIBackend
        Singleton instance of the backend.
    """
    if cls._instance is None:
        cls._instance = cls()
    return cls._instance

APIBackendBuilder

APIBackendBuilder(api_version: APIVersion, fallback_api_version: APIVersion | None = None)

Builder for constructing API backend instances with all resource-specific APIs.

This class organizes resource-specific API objects (datasets, tasks, flows, evaluations, runs, setups, studies, etc.) and provides a centralized access point for both the primary API version and an optional fallback API version.

The constructor automatically initializes:

• HTTPClient for the primary API version
• Optional HTTPClient for a fallback API version
• MinIOClient for file storage operations
• Resource-specific API instances, optionally wrapped with fallback proxies

PARAMETER	DESCRIPTION
api_version	The primary API version to use for all resource APIs and HTTP communication. TYPE: APIVersion
fallback_api_version	Optional fallback API version to wrap resource APIs with a FallbackProxy. TYPE: APIVersion | None DEFAULT: None

ATTRIBUTE	DESCRIPTION
dataset	API interface for dataset resources. TYPE: ResourceAPI | FallbackProxy
task	API interface for task resources. TYPE: ResourceAPI | FallbackProxy
evaluation_measure	API interface for evaluation measure resources. TYPE: ResourceAPI | FallbackProxy
estimation_procedure	API interface for estimation procedure resources. TYPE: ResourceAPI | FallbackProxy
evaluation	API interface for evaluation resources. TYPE: ResourceAPI | FallbackProxy
flow	API interface for flow resources. TYPE: ResourceAPI | FallbackProxy
study	API interface for study resources. TYPE: ResourceAPI | FallbackProxy
run	API interface for run resources. TYPE: ResourceAPI | FallbackProxy
setup	API interface for setup resources. TYPE: ResourceAPI | FallbackProxy
http_client	Client for HTTP communication using the primary API version. TYPE: HTTPClient
fallback_http_client	Client for HTTP communication using the fallback API version, if provided. TYPE: HTTPClient | None
minio_client	Client for file storage operations (MinIO/S3). TYPE: MinIOClient

Source code in openml/_api/setup/builder.py

def __init__(self, api_version: APIVersion, fallback_api_version: APIVersion | None = None):
    # initialize clients and resource APIs in-place
    self._build(api_version, fallback_api_version)

DatasetAPI

DatasetAPI(http: HTTPClient, minio: MinIOClient)

Bases: ResourceAPI

Abstract API interface for dataset resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete abstractmethod

delete(resource_id: int) -> bool

Delete a resource by its identifier.

PARAMETER	DESCRIPTION
resource_id	Unique identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the deletion was successful.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

publish abstractmethod

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource to the OpenML server.

PARAMETER	DESCRIPTION
path	API endpoint path used for publishing the resource. TYPE: str
files	Files or payload data required for publishing. The structure depends on the resource type. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

tag abstractmethod

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

untag abstractmethod

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

DatasetV1API

DatasetV1API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV1API, DatasetAPI

Version 1 API implementation for dataset resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete

delete(resource_id: int) -> bool

Delete a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the server confirms successful deletion.

RAISES	DESCRIPTION
ValueError	If the resource type is not supported for deletion.
OpenMLNotAuthorizedError	If the user is not permitted to delete the resource.
OpenMLServerError	If deletion fails for an unknown reason.
OpenMLServerException	For other server-side errors.

Source code in openml/_api/resources/base/versions.py

def delete(self, resource_id: int) -> bool:
    """
    Delete a resource using the V1 API.

    Parameters
    ----------
    resource_id : int
        Identifier of the resource to delete.

    Returns
    -------
    bool
        ``True`` if the server confirms successful deletion.

    Raises
    ------
    ValueError
        If the resource type is not supported for deletion.
    OpenMLNotAuthorizedError
        If the user is not permitted to delete the resource.
    OpenMLServerError
        If deletion fails for an unknown reason.
    OpenMLServerException
        For other server-side errors.
    """
    if self.resource_type not in _LEGAL_RESOURCES_DELETE:
        raise ValueError(f"Can't delete a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/{resource_id}"
    try:
        response = self._http.delete(path)
        result = xmltodict.parse(response.content)
        return f"oml:{endpoint_name}_delete" in result
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

publish

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource using the V1 API.

PARAMETER	DESCRIPTION
path	API endpoint path for the upload. TYPE: str
files	Files to upload as part of the request payload. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

RAISES	DESCRIPTION
ValueError	If the server response does not contain a valid resource ID.
OpenMLServerException	If the server returns an error during upload.

Source code in openml/_api/resources/base/versions.py

def publish(self, path: str, files: Mapping[str, Any] | None) -> int:
    """
    Publish a new resource using the V1 API.

    Parameters
    ----------
    path : str
        API endpoint path for the upload.
    files : Mapping of str to Any or None
        Files to upload as part of the request payload.

    Returns
    -------
    int
        Identifier of the newly created resource.

    Raises
    ------
    ValueError
        If the server response does not contain a valid resource ID.
    OpenMLServerException
        If the server returns an error during upload.
    """
    response = self._http.post(path, files=files)
    parsed_response = xmltodict.parse(response.content)
    return self._extract_id_from_upload(parsed_response)

tag

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def tag(self, resource_id: int, tag: str) -> list[str]:
    """
    Add a tag to a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't tag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/tag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_tag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

untag

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def untag(self, resource_id: int, tag: str) -> list[str]:
    """
    Remove a tag from a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't untag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/untag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_untag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

DatasetV2API

DatasetV2API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV2API, DatasetAPI

Version 2 API implementation for dataset resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

EstimationProcedureAPI

EstimationProcedureAPI(http: HTTPClient, minio: MinIOClient)

Bases: ResourceAPI

Abstract API interface for estimation procedure resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete abstractmethod

delete(resource_id: int) -> bool

Delete a resource by its identifier.

PARAMETER	DESCRIPTION
resource_id	Unique identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the deletion was successful.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

publish abstractmethod

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource to the OpenML server.

PARAMETER	DESCRIPTION
path	API endpoint path used for publishing the resource. TYPE: str
files	Files or payload data required for publishing. The structure depends on the resource type. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

tag abstractmethod

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

untag abstractmethod

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

EstimationProcedureV1API

EstimationProcedureV1API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV1API, EstimationProcedureAPI

V1 API implementation for estimation procedures.

Fetches estimation procedures from the v1 XML API endpoint.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete

delete(resource_id: int) -> bool

Delete a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the server confirms successful deletion.

RAISES	DESCRIPTION
ValueError	If the resource type is not supported for deletion.
OpenMLNotAuthorizedError	If the user is not permitted to delete the resource.
OpenMLServerError	If deletion fails for an unknown reason.
OpenMLServerException	For other server-side errors.

Source code in openml/_api/resources/base/versions.py

def delete(self, resource_id: int) -> bool:
    """
    Delete a resource using the V1 API.

    Parameters
    ----------
    resource_id : int
        Identifier of the resource to delete.

    Returns
    -------
    bool
        ``True`` if the server confirms successful deletion.

    Raises
    ------
    ValueError
        If the resource type is not supported for deletion.
    OpenMLNotAuthorizedError
        If the user is not permitted to delete the resource.
    OpenMLServerError
        If deletion fails for an unknown reason.
    OpenMLServerException
        For other server-side errors.
    """
    if self.resource_type not in _LEGAL_RESOURCES_DELETE:
        raise ValueError(f"Can't delete a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/{resource_id}"
    try:
        response = self._http.delete(path)
        result = xmltodict.parse(response.content)
        return f"oml:{endpoint_name}_delete" in result
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

list

list() -> list[OpenMLEstimationProcedure]

Return a list of all estimation procedures which are on OpenML.

RETURNS	DESCRIPTION
procedures	A list of all estimation procedures. Every procedure is represented by a dictionary containing the following information: id, task type id, name, type, repeats, folds, stratified. TYPE: list

Source code in openml/_api/resources/estimation_procedure.py

def list(self) -> list[OpenMLEstimationProcedure]:
    """Return a list of all estimation procedures which are on OpenML.

    Returns
    -------
    procedures : list
        A list of all estimation procedures. Every procedure is represented by
        a dictionary containing the following information: id, task type id,
        name, type, repeats, folds, stratified.
    """
    path = "estimationprocedure/list"
    response = self._http.get(path)
    xml_content = response.text

    procs_dict = xmltodict.parse(xml_content)

    # Minimalistic check if the XML is useful
    if "oml:estimationprocedures" not in procs_dict:
        raise ValueError("Error in return XML, does not contain tag oml:estimationprocedures.")

    if "@xmlns:oml" not in procs_dict["oml:estimationprocedures"]:
        raise ValueError(
            "Error in return XML, does not contain tag "
            "@xmlns:oml as a child of oml:estimationprocedures.",
        )

    if procs_dict["oml:estimationprocedures"]["@xmlns:oml"] != "http://openml.org/openml":
        raise ValueError(
            "Error in return XML, value of "
            "oml:estimationprocedures/@xmlns:oml is not "
            "http://openml.org/openml, but {}".format(
                str(procs_dict["oml:estimationprocedures"]["@xmlns:oml"])
            ),
        )

    procs: list[OpenMLEstimationProcedure] = []
    for proc_ in procs_dict["oml:estimationprocedures"]["oml:estimationprocedure"]:
        task_type_int = int(proc_["oml:ttid"])
        try:
            task_type_id = TaskType(task_type_int)
            procs.append(
                OpenMLEstimationProcedure(
                    id=int(proc_["oml:id"]),
                    task_type_id=task_type_id,
                    name=proc_["oml:name"],
                    type=proc_["oml:type"],
                )
            )
        except ValueError as e:
            warnings.warn(
                f"Could not create task type id for {task_type_int} due to error {e}",
                RuntimeWarning,
                stacklevel=2,
            )

    return procs

publish

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource using the V1 API.

PARAMETER	DESCRIPTION
path	API endpoint path for the upload. TYPE: str
files	Files to upload as part of the request payload. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

RAISES	DESCRIPTION
ValueError	If the server response does not contain a valid resource ID.
OpenMLServerException	If the server returns an error during upload.

Source code in openml/_api/resources/base/versions.py

def publish(self, path: str, files: Mapping[str, Any] | None) -> int:
    """
    Publish a new resource using the V1 API.

    Parameters
    ----------
    path : str
        API endpoint path for the upload.
    files : Mapping of str to Any or None
        Files to upload as part of the request payload.

    Returns
    -------
    int
        Identifier of the newly created resource.

    Raises
    ------
    ValueError
        If the server response does not contain a valid resource ID.
    OpenMLServerException
        If the server returns an error during upload.
    """
    response = self._http.post(path, files=files)
    parsed_response = xmltodict.parse(response.content)
    return self._extract_id_from_upload(parsed_response)

tag

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def tag(self, resource_id: int, tag: str) -> list[str]:
    """
    Add a tag to a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't tag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/tag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_tag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

untag

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def untag(self, resource_id: int, tag: str) -> list[str]:
    """
    Remove a tag from a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't untag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/untag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_untag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

EstimationProcedureV2API

EstimationProcedureV2API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV2API, EstimationProcedureAPI

V2 API implementation for estimation procedures.

Fetches estimation procedures from the v2 JSON API endpoint.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

EvaluationAPI

EvaluationAPI(http: HTTPClient, minio: MinIOClient)

Bases: ResourceAPI

Abstract API interface for evaluation resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete abstractmethod

delete(resource_id: int) -> bool

Delete a resource by its identifier.

PARAMETER	DESCRIPTION
resource_id	Unique identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the deletion was successful.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

publish abstractmethod

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource to the OpenML server.

PARAMETER	DESCRIPTION
path	API endpoint path used for publishing the resource. TYPE: str
files	Files or payload data required for publishing. The structure depends on the resource type. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

tag abstractmethod

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

untag abstractmethod

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

EvaluationMeasureAPI

EvaluationMeasureAPI(http: HTTPClient, minio: MinIOClient)

Bases: ResourceAPI

Abstract API interface for evaluation measure resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete abstractmethod

delete(resource_id: int) -> bool

Delete a resource by its identifier.

PARAMETER	DESCRIPTION
resource_id	Unique identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the deletion was successful.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

publish abstractmethod

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource to the OpenML server.

PARAMETER	DESCRIPTION
path	API endpoint path used for publishing the resource. TYPE: str
files	Files or payload data required for publishing. The structure depends on the resource type. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

tag abstractmethod

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

untag abstractmethod

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

EvaluationMeasureV1API

EvaluationMeasureV1API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV1API, EvaluationMeasureAPI

V1 API implementation for evaluation measures.

Fetches evaluation measures from the v1 XML API endpoint.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete

delete(resource_id: int) -> bool

Delete a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the server confirms successful deletion.

RAISES	DESCRIPTION
ValueError	If the resource type is not supported for deletion.
OpenMLNotAuthorizedError	If the user is not permitted to delete the resource.
OpenMLServerError	If deletion fails for an unknown reason.
OpenMLServerException	For other server-side errors.

Source code in openml/_api/resources/base/versions.py

def delete(self, resource_id: int) -> bool:
    """
    Delete a resource using the V1 API.

    Parameters
    ----------
    resource_id : int
        Identifier of the resource to delete.

    Returns
    -------
    bool
        ``True`` if the server confirms successful deletion.

    Raises
    ------
    ValueError
        If the resource type is not supported for deletion.
    OpenMLNotAuthorizedError
        If the user is not permitted to delete the resource.
    OpenMLServerError
        If deletion fails for an unknown reason.
    OpenMLServerException
        For other server-side errors.
    """
    if self.resource_type not in _LEGAL_RESOURCES_DELETE:
        raise ValueError(f"Can't delete a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/{resource_id}"
    try:
        response = self._http.delete(path)
        result = xmltodict.parse(response.content)
        return f"oml:{endpoint_name}_delete" in result
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

list

list() -> list[str]

List all evaluation measures available on OpenML.

RETURNS	DESCRIPTION
list[str]	A list of evaluation measure names.

Source code in openml/_api/resources/evaluation_measure.py

def list(self) -> list[str]:
    """List all evaluation measures available on OpenML.

    Returns
    -------
    list[str]
        A list of evaluation measure names.
    """
    path = "evaluationmeasure/list"
    response = self._http.get(path)
    xml_content = response.text

    qualities = xmltodict.parse(xml_content, force_list=("oml:measures"))
    # Minimalistic check if the XML is useful
    if "oml:evaluation_measures" not in qualities:
        raise ValueError('Error in return XML, does not contain "oml:evaluation_measures"')

    if not isinstance(
        qualities["oml:evaluation_measures"]["oml:measures"][0]["oml:measure"], list
    ):
        raise TypeError('Error in return XML, does not contain "oml:measure" as a list')

    return qualities["oml:evaluation_measures"]["oml:measures"][0]["oml:measure"]

publish

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource using the V1 API.

PARAMETER	DESCRIPTION
path	API endpoint path for the upload. TYPE: str
files	Files to upload as part of the request payload. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

RAISES	DESCRIPTION
ValueError	If the server response does not contain a valid resource ID.
OpenMLServerException	If the server returns an error during upload.

Source code in openml/_api/resources/base/versions.py

def publish(self, path: str, files: Mapping[str, Any] | None) -> int:
    """
    Publish a new resource using the V1 API.

    Parameters
    ----------
    path : str
        API endpoint path for the upload.
    files : Mapping of str to Any or None
        Files to upload as part of the request payload.

    Returns
    -------
    int
        Identifier of the newly created resource.

    Raises
    ------
    ValueError
        If the server response does not contain a valid resource ID.
    OpenMLServerException
        If the server returns an error during upload.
    """
    response = self._http.post(path, files=files)
    parsed_response = xmltodict.parse(response.content)
    return self._extract_id_from_upload(parsed_response)

tag

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def tag(self, resource_id: int, tag: str) -> list[str]:
    """
    Add a tag to a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't tag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/tag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_tag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

untag

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def untag(self, resource_id: int, tag: str) -> list[str]:
    """
    Remove a tag from a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't untag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/untag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_untag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

EvaluationMeasureV2API

EvaluationMeasureV2API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV2API, EvaluationMeasureAPI

V2 API implementation for evaluation measures.

Fetches evaluation measures from the v2 JSON API endpoint.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

list

list() -> list[str]

List all evaluation measures available on OpenML.

RETURNS	DESCRIPTION
list[str]	A list of evaluation measure names.

Source code in openml/_api/resources/evaluation_measure.py

def list(self) -> list[str]:
    """List all evaluation measures available on OpenML.

    Returns
    -------
    list[str]
        A list of evaluation measure names.
    """
    path = "evaluationmeasure/list"
    response = self._http.get(path)
    data = response.json()

    if not isinstance(data, list):
        raise ValueError(f"Expected list, got {type(data)}")

    return data

EvaluationV1API

EvaluationV1API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV1API, EvaluationAPI

V1 API implementation for evaluations. Fetches evaluations from the v1 XML API endpoint.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete

delete(resource_id: int) -> bool

Delete a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the server confirms successful deletion.

RAISES	DESCRIPTION
ValueError	If the resource type is not supported for deletion.
OpenMLNotAuthorizedError	If the user is not permitted to delete the resource.
OpenMLServerError	If deletion fails for an unknown reason.
OpenMLServerException	For other server-side errors.

Source code in openml/_api/resources/base/versions.py

def delete(self, resource_id: int) -> bool:
    """
    Delete a resource using the V1 API.

    Parameters
    ----------
    resource_id : int
        Identifier of the resource to delete.

    Returns
    -------
    bool
        ``True`` if the server confirms successful deletion.

    Raises
    ------
    ValueError
        If the resource type is not supported for deletion.
    OpenMLNotAuthorizedError
        If the user is not permitted to delete the resource.
    OpenMLServerError
        If deletion fails for an unknown reason.
    OpenMLServerException
        For other server-side errors.
    """
    if self.resource_type not in _LEGAL_RESOURCES_DELETE:
        raise ValueError(f"Can't delete a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/{resource_id}"
    try:
        response = self._http.delete(path)
        result = xmltodict.parse(response.content)
        return f"oml:{endpoint_name}_delete" in result
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

list

list(limit: int, offset: int, *, function: str, tasks: list | None = None, setups: list | None = None, flows: list | None = None, runs: list | None = None, uploaders: list | None = None, study: int | None = None, sort_order: str | None = None, **kwargs: Any) -> list[OpenMLEvaluation]

Retrieve evaluations from the OpenML v1 XML API.

This method builds an evaluation query URL based on the provided filters, sends a request to the OpenML v1 endpoint, parses the XML response into a dictionary, and enriches the result with uploader usernames.

PARAMETER	DESCRIPTION
The
ones
limit	the number of evaluations to return TYPE: int
offset	the number of evaluations to skip, starting from the first TYPE: int
function	the evaluation function. e.g., predictive_accuracy TYPE: str
tasks	the list of task IDs TYPE: list[int, str] DEFAULT: None
setups	the list of setup IDs TYPE: list | None DEFAULT: None
flows	the list of flow IDs TYPE: list[int, str] DEFAULT: None
runs	the list of run IDs TYPE: list | None DEFAULT: None
uploaders	the list of uploader IDs TYPE: list[int, str] DEFAULT: None
study	TYPE: int DEFAULT: None
kwargs	Legal filter operators: tag, per_fold TYPE: Any DEFAULT: {}
sort_order	order of sorting evaluations, ascending ("asc") or descending ("desc") TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
list of OpenMLEvaluation objects

Notes

This method performs two API calls: 1. Fetches evaluation data from the specified endpoint 2. Fetches user information for all uploaders in the evaluation data

The user information is used to map uploader IDs to usernames.

Source code in openml/_api/resources/evaluation.py

def list(  # noqa: PLR0913
    self,
    limit: int,
    offset: int,
    *,
    function: str,
    tasks: builtins.list | None = None,
    setups: builtins.list | None = None,
    flows: builtins.list | None = None,
    runs: builtins.list | None = None,
    uploaders: builtins.list | None = None,
    study: int | None = None,
    sort_order: str | None = None,
    **kwargs: Any,
) -> builtins.list[OpenMLEvaluation]:
    """Retrieve evaluations from the OpenML v1 XML API.

    This method builds an evaluation query URL based on the provided
    filters, sends a request to the OpenML v1 endpoint, parses the XML
    response into a dictionary, and enriches the result with uploader
    usernames.

    Parameters
    ----------
    The arguments that are lists are separated from the single value
    ones which are put into the kwargs.

    limit : int
        the number of evaluations to return
    offset : int
        the number of evaluations to skip, starting from the first
    function : str
        the evaluation function. e.g., predictive_accuracy

    tasks : list[int,str], optional
        the list of task IDs
    setups: list[int,str], optional
        the list of setup IDs
    flows : list[int,str], optional
        the list of flow IDs
    runs :list[int,str], optional
        the list of run IDs
    uploaders : list[int,str], optional
        the list of uploader IDs

    study : int, optional

    kwargs: dict, optional
        Legal filter operators: tag, per_fold

    sort_order : str, optional
        order of sorting evaluations, ascending ("asc") or descending ("desc")

    Returns
    -------
    list of OpenMLEvaluation objects

    Notes
    -----
    This method performs two API calls:
    1. Fetches evaluation data from the specified endpoint
    2. Fetches user information for all uploaders in the evaluation data

    The user information is used to map uploader IDs to usernames.
    """
    api_call = self._build_url(
        limit,
        offset,
        function=function,
        tasks=tasks,
        setups=setups,
        flows=flows,
        runs=runs,
        uploaders=uploaders,
        study=study,
        sort_order=sort_order,
        **kwargs,
    )

    eval_response = self._http.get(api_call)
    xml_content = eval_response.text

    return self._parse_list_xml(xml_content)

publish

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource using the V1 API.

PARAMETER	DESCRIPTION
path	API endpoint path for the upload. TYPE: str
files	Files to upload as part of the request payload. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

RAISES	DESCRIPTION
ValueError	If the server response does not contain a valid resource ID.
OpenMLServerException	If the server returns an error during upload.

Source code in openml/_api/resources/base/versions.py

def publish(self, path: str, files: Mapping[str, Any] | None) -> int:
    """
    Publish a new resource using the V1 API.

    Parameters
    ----------
    path : str
        API endpoint path for the upload.
    files : Mapping of str to Any or None
        Files to upload as part of the request payload.

    Returns
    -------
    int
        Identifier of the newly created resource.

    Raises
    ------
    ValueError
        If the server response does not contain a valid resource ID.
    OpenMLServerException
        If the server returns an error during upload.
    """
    response = self._http.post(path, files=files)
    parsed_response = xmltodict.parse(response.content)
    return self._extract_id_from_upload(parsed_response)

tag

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def tag(self, resource_id: int, tag: str) -> list[str]:
    """
    Add a tag to a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't tag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/tag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_tag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

untag

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def untag(self, resource_id: int, tag: str) -> list[str]:
    """
    Remove a tag from a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't untag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/untag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_untag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

EvaluationV2API

EvaluationV2API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV2API, EvaluationAPI

V2 API implementation for evaluations. Fetches evaluations from the v2 json API endpoint.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

list

list(limit: int, offset: int, *, function: str, tasks: list | None = None, setups: list | None = None, flows: list | None = None, runs: list | None = None, uploaders: list | None = None, study: int | None = None, sort_order: str | None = None, **kwargs: Any) -> list[OpenMLEvaluation]

Retrieve evaluation results from the OpenML v2 JSON API.

Notes

This method is not yet implemented.

Source code in openml/_api/resources/evaluation.py

def list(  # noqa: PLR0913
    self,
    limit: int,  # noqa: ARG002
    offset: int,  # noqa: ARG002
    *,
    function: str,  # noqa: ARG002
    tasks: builtins.list | None = None,  # noqa: ARG002
    setups: builtins.list | None = None,  # noqa: ARG002
    flows: builtins.list | None = None,  # noqa: ARG002
    runs: builtins.list | None = None,  # noqa: ARG002
    uploaders: builtins.list | None = None,  # noqa: ARG002
    study: int | None = None,  # noqa: ARG002
    sort_order: str | None = None,  # noqa: ARG002
    **kwargs: Any,  # noqa: ARG002
) -> builtins.list[OpenMLEvaluation]:
    """
    Retrieve evaluation results from the OpenML v2 JSON API.

    Notes
    -----
    This method is not yet implemented.
    """
    self._not_supported(method="list")

FallbackProxy

FallbackProxy(*api_versions: Any)

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.

PARAMETER	DESCRIPTION
*api_versions	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. TYPE: Any DEFAULT: ()

RAISES	DESCRIPTION
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.

Source code in openml/_api/resources/base/fallback.py

def __init__(self, *api_versions: Any):
    if not api_versions:
        raise ValueError("At least one API version must be provided")
    self._apis = api_versions

__getattr__

__getattr__(name: str) -> Any

Dynamically resolve attribute access across API implementations.

PARAMETER	DESCRIPTION
name	Name of the attribute being accessed. TYPE: str

RETURNS	DESCRIPTION
Any	The resolved attribute. If it is callable, a wrapped function providing fallback behavior is returned.

RAISES	DESCRIPTION
AttributeError	If none of the API implementations define the attribute.

Source code in openml/_api/resources/base/fallback.py

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

FlowAPI

FlowAPI(http: HTTPClient, minio: MinIOClient)

Bases: ResourceAPI

Abstract API interface for flow resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete abstractmethod

delete(resource_id: int) -> bool

Delete a resource by its identifier.

PARAMETER	DESCRIPTION
resource_id	Unique identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the deletion was successful.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

publish abstractmethod

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource to the OpenML server.

PARAMETER	DESCRIPTION
path	API endpoint path used for publishing the resource. TYPE: str
files	Files or payload data required for publishing. The structure depends on the resource type. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

tag abstractmethod

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

untag abstractmethod

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

FlowV1API

FlowV1API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV1API, FlowAPI

Version 1 API implementation for flow resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete

delete(resource_id: int) -> bool

Delete a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the server confirms successful deletion.

RAISES	DESCRIPTION
ValueError	If the resource type is not supported for deletion.
OpenMLNotAuthorizedError	If the user is not permitted to delete the resource.
OpenMLServerError	If deletion fails for an unknown reason.
OpenMLServerException	For other server-side errors.

Source code in openml/_api/resources/base/versions.py

def delete(self, resource_id: int) -> bool:
    """
    Delete a resource using the V1 API.

    Parameters
    ----------
    resource_id : int
        Identifier of the resource to delete.

    Returns
    -------
    bool
        ``True`` if the server confirms successful deletion.

    Raises
    ------
    ValueError
        If the resource type is not supported for deletion.
    OpenMLNotAuthorizedError
        If the user is not permitted to delete the resource.
    OpenMLServerError
        If deletion fails for an unknown reason.
    OpenMLServerException
        For other server-side errors.
    """
    if self.resource_type not in _LEGAL_RESOURCES_DELETE:
        raise ValueError(f"Can't delete a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/{resource_id}"
    try:
        response = self._http.delete(path)
        result = xmltodict.parse(response.content)
        return f"oml:{endpoint_name}_delete" in result
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

publish

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource using the V1 API.

PARAMETER	DESCRIPTION
path	API endpoint path for the upload. TYPE: str
files	Files to upload as part of the request payload. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

RAISES	DESCRIPTION
ValueError	If the server response does not contain a valid resource ID.
OpenMLServerException	If the server returns an error during upload.

Source code in openml/_api/resources/base/versions.py

def publish(self, path: str, files: Mapping[str, Any] | None) -> int:
    """
    Publish a new resource using the V1 API.

    Parameters
    ----------
    path : str
        API endpoint path for the upload.
    files : Mapping of str to Any or None
        Files to upload as part of the request payload.

    Returns
    -------
    int
        Identifier of the newly created resource.

    Raises
    ------
    ValueError
        If the server response does not contain a valid resource ID.
    OpenMLServerException
        If the server returns an error during upload.
    """
    response = self._http.post(path, files=files)
    parsed_response = xmltodict.parse(response.content)
    return self._extract_id_from_upload(parsed_response)

tag

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def tag(self, resource_id: int, tag: str) -> list[str]:
    """
    Add a tag to a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't tag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/tag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_tag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

untag

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def untag(self, resource_id: int, tag: str) -> list[str]:
    """
    Remove a tag from a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't untag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/untag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_untag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

FlowV2API

FlowV2API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV2API, FlowAPI

Version 2 API implementation for flow resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

HTTPCache

Filesystem-based cache for HTTP responses.

This class stores HTTP responses on disk using a structured directory layout derived from the request URL and parameters. Each cached response consists of three files: metadata (meta.json), headers (headers.json), and the raw body (body.bin).

Notes

The cache key is derived from the URL (domain and path components) and query parameters, excluding the api_key parameter.

get_key

get_key(url: str, params: dict[str, Any]) -> str

Generate a filesystem-safe cache key for a request.

The key is constructed from URL path segments and URL-encoded query parameters (excluding api_key).

PARAMETER	DESCRIPTION
url	The full request URL. TYPE: str
params	Query parameters associated with the request. TYPE: dict of str to Any

RETURNS	DESCRIPTION
str	A relative path string representing the cache key.

Source code in openml/_api/clients/http.py

def get_key(self, url: str, params: dict[str, Any]) -> str:
    """
    Generate a filesystem-safe cache key for a request.

    The key is constructed from URL path segments and
    URL-encoded query parameters (excluding ``api_key``).

    Parameters
    ----------
    url : str
        The full request URL.
    params : dict of str to Any
        Query parameters associated with the request.

    Returns
    -------
    str
        A relative path string representing the cache key.
    """
    parsed_url = urlparse(url)
    path_parts = parsed_url.path.strip("/").split("/")

    filtered_params = {k: v for k, v in params.items() if k != "api_key"}
    params_part = [urlencode(filtered_params)] if filtered_params else []

    return str(Path(*path_parts, *params_part))

load

load(key: str) -> Response

Load a cached HTTP response from disk.

PARAMETER	DESCRIPTION
key	Cache key identifying the stored response. TYPE: str

RETURNS	DESCRIPTION
Response	Reconstructed response object with status code, headers, body, and metadata.

RAISES	DESCRIPTION
FileNotFoundError	If the cache entry or required files are missing.
ValueError	If required metadata is missing or malformed.

Source code in openml/_api/clients/http.py

def load(self, key: str) -> Response:
    """
    Load a cached HTTP response from disk.

    Parameters
    ----------
    key : str
        Cache key identifying the stored response.

    Returns
    -------
    requests.Response
        Reconstructed response object with status code, headers, body, and metadata.

    Raises
    ------
    FileNotFoundError
        If the cache entry or required files are missing.
    ValueError
        If required metadata is missing or malformed.
    """
    path = self._key_to_path(key)

    meta_path = path / "meta.json"
    meta_raw = meta_path.read_bytes() if meta_path.exists() else "{}"
    meta = json.loads(meta_raw)

    headers_path = path / "headers.json"
    headers_raw = headers_path.read_bytes() if headers_path.exists() else "{}"
    headers = json.loads(headers_raw)

    body_path = path / self._get_body_filename_from_path(path)
    if not body_path.exists():
        raise FileNotFoundError(f"Incomplete cache at {body_path}")
    body = body_path.read_bytes()

    response = Response()
    response.headers = headers
    response._content = body
    response.status_code = meta.get("status_code")
    response.url = meta.get("url")
    response.reason = meta.get("reason")
    response.encoding = meta.get("encoding")

    return response

save

save(key: str, response: Response) -> None

Persist an HTTP response to disk.

PARAMETER	DESCRIPTION
key	Cache key identifying where to store the response. TYPE: str
response	Response object to cache. TYPE: Response

Notes

The response body is stored as binary data. Headers and metadata (status code, URL, reason, encoding, elapsed time, request info, and creation timestamp) are stored as JSON.

Source code in openml/_api/clients/http.py

def save(self, key: str, response: Response) -> None:
    """
    Persist an HTTP response to disk.

    Parameters
    ----------
    key : str
        Cache key identifying where to store the response.
    response : requests.Response
        Response object to cache.

    Notes
    -----
    The response body is stored as binary data. Headers and metadata
    (status code, URL, reason, encoding, elapsed time, request info, and
    creation timestamp) are stored as JSON.
    """
    path = self._key_to_path(key)
    path.mkdir(parents=True, exist_ok=True)

    body_filename = self._get_body_filename_from_response(response)
    with (path / body_filename).open("wb") as f:
        f.write(response.content)

    with (path / "headers.json").open("w", encoding="utf-8") as f:
        json.dump(dict(response.headers), f)

    meta = {
        "status_code": response.status_code,
        "url": response.url,
        "reason": response.reason,
        "encoding": response.encoding,
        "created_at": time.time(),
        "request": {
            "method": response.request.method if response.request else None,
            "url": response.request.url if response.request else None,
            "headers": dict(response.request.headers) if response.request else None,
            "body": response.request.body if response.request else None,
        },
    }

    with (path / "meta.json").open("w", encoding="utf-8") as f:
        json.dump(meta, f)

HTTPClient

HTTPClient(*, api_version: APIVersion)

HTTP client for interacting with the OpenML API.

This client supports configurable retry policies, optional filesystem caching, API key authentication, and response validation including checksum verification.

PARAMETER	DESCRIPTION
api_version	Backend API Version. TYPE: APIVersion

Source code in openml/_api/clients/http.py

def __init__(
    self,
    *,
    api_version: APIVersion,
) -> None:
    self.api_version = api_version

    self.cache = HTTPCache()

__request

__request(session: Session, method: str, url: str, params: Mapping[str, Any], data: Mapping[str, Any], headers: Mapping[str, str], files: Mapping[str, Any] | None, **request_kwargs: Any) -> tuple[Response | None, Exception | None]

Execute a single HTTP request attempt.

PARAMETER	DESCRIPTION
session	Active session used to send the request. TYPE: Session
method	HTTP method (e.g., GET, POST). TYPE: str
url	Full request URL. TYPE: str
params	Query parameters. TYPE: Mapping of str to Any
data	Request body data. TYPE: Mapping of str to Any
headers	HTTP headers. TYPE: Mapping of str to str
files	Files to upload. TYPE: Mapping of str to Any or None
**request_kwargs	Additional arguments forwarded to requests.Session.request. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
tuple of (requests.Response or None, Exception or None)	Response and potential retry exception.

Source code in openml/_api/clients/http.py

def __request(  # noqa: PLR0913
    self,
    session: requests.Session,
    method: str,
    url: str,
    params: Mapping[str, Any],
    data: Mapping[str, Any],
    headers: Mapping[str, str],
    files: Mapping[str, Any] | None,
    **request_kwargs: Any,
) -> tuple[Response | None, Exception | None]:
    """
    Execute a single HTTP request attempt.

    Parameters
    ----------
    session : requests.Session
        Active session used to send the request.
    method : str
        HTTP method (e.g., ``GET``, ``POST``).
    url : str
        Full request URL.
    params : Mapping of str to Any
        Query parameters.
    data : Mapping of str to Any
        Request body data.
    headers : Mapping of str to str
        HTTP headers.
    files : Mapping of str to Any or None
        Files to upload.
    **request_kwargs : Any
        Additional arguments forwarded to ``requests.Session.request``.

    Returns
    -------
    tuple of (requests.Response or None, Exception or None)
        Response and potential retry exception.
    """
    exception: Exception | None = None
    response: Response | None = None

    try:
        response = session.request(
            method=method,
            url=url,
            params=params,
            data=data,
            headers=headers,
            files=files,
            **request_kwargs,
        )
    except (
        requests.exceptions.ChunkedEncodingError,
        requests.exceptions.ConnectionError,
        requests.exceptions.SSLError,
    ) as e:
        exception = e

    if response is not None:
        exception = self._validate_response(
            method=method,
            url=url,
            files=files,
            response=response,
        )

    return response, exception

delete

delete(path: str, **request_kwargs: Any) -> Response

Send a DELETE request.

PARAMETER	DESCRIPTION
path	API path relative to the base URL. TYPE: str
**request_kwargs	Additional request arguments. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
Response	HTTP response.

Source code in openml/_api/clients/http.py

def delete(
    self,
    path: str,
    **request_kwargs: Any,
) -> Response:
    """
    Send a DELETE request.

    Parameters
    ----------
    path : str
        API path relative to the base URL.
    **request_kwargs : Any
        Additional request arguments.

    Returns
    -------
    requests.Response
        HTTP response.
    """
    return self._request(
        method="DELETE",
        path=path,
        enable_cache=False,
        use_api_key=True,
        **request_kwargs,
    )

download

download(url: str, handler: Callable[[Response, Path, str], None] | None = None, encoding: str = 'utf-8', file_name: str = 'response.txt', md5_checksum: str | None = None) -> Path

Download a resource and store it in the cache directory.

PARAMETER	DESCRIPTION
url	Absolute URL of the resource to download. TYPE: str
handler	Custom handler function accepting (response, path, encoding) and returning a pathlib.Path. TYPE: callable or None DEFAULT: None
encoding	Text encoding used when writing the response body. TYPE: str DEFAULT: 'utf-8'
file_name	Name of the saved file. TYPE: str DEFAULT: 'response.txt'
md5_checksum	Expected MD5 checksum for integrity verification. TYPE: str or None DEFAULT: None

RETURNS	DESCRIPTION
Path	Path to the downloaded file.

RAISES	DESCRIPTION
OpenMLHashException	If checksum verification fails.

Source code in openml/_api/clients/http.py

def download(
    self,
    url: str,
    handler: Callable[[Response, Path, str], None] | None = None,
    encoding: str = "utf-8",
    file_name: str = "response.txt",
    md5_checksum: str | None = None,
) -> Path:
    """
    Download a resource and store it in the cache directory.

    Parameters
    ----------
    url : str
        Absolute URL of the resource to download.
    handler : callable or None, optional
        Custom handler function accepting ``(response, path, encoding)``
        and returning a ``pathlib.Path``.
    encoding : str, optional
        Text encoding used when writing the response body.
    file_name : str, optional
        Name of the saved file.
    md5_checksum : str or None, optional
        Expected MD5 checksum for integrity verification.

    Returns
    -------
    pathlib.Path
        Path to the downloaded file.

    Raises
    ------
    OpenMLHashException
        If checksum verification fails.
    """
    base = self.cache.path
    file_path = base / "downloads" / urlparse(url).path.lstrip("/") / file_name
    file_path = file_path.expanduser()
    file_path.parent.mkdir(parents=True, exist_ok=True)
    if file_path.exists():
        return file_path

    response = self.get(url, md5_checksum=md5_checksum)

    def write_to_file(response: Response, path: Path, encoding: str) -> None:
        path.write_text(response.text, encoding)

    handler = handler or write_to_file
    handler(response, file_path, encoding)
    return file_path

get

get(path: str, *, enable_cache: bool = False, refresh_cache: bool = False, use_api_key: bool = False, md5_checksum: str | None = None, **request_kwargs: Any) -> Response

Send a GET request.

PARAMETER	DESCRIPTION
path	API path relative to the base URL. TYPE: str
enable_cache	Whether to use the response cache. TYPE: bool DEFAULT: False
refresh_cache	Whether to ignore existing cached entries. TYPE: bool DEFAULT: False
use_api_key	Whether to include the API key. TYPE: bool DEFAULT: False
md5_checksum	Expected MD5 checksum for response validation. TYPE: str or None DEFAULT: None
**request_kwargs	Additional request arguments. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
Response	HTTP response.

Source code in openml/_api/clients/http.py

def get(
    self,
    path: str,
    *,
    enable_cache: bool = False,
    refresh_cache: bool = False,
    use_api_key: bool = False,
    md5_checksum: str | None = None,
    **request_kwargs: Any,
) -> Response:
    """
    Send a GET request.

    Parameters
    ----------
    path : str
        API path relative to the base URL.
    enable_cache : bool, optional
        Whether to use the response cache.
    refresh_cache : bool, optional
        Whether to ignore existing cached entries.
    use_api_key : bool, optional
        Whether to include the API key.
    md5_checksum : str or None, optional
        Expected MD5 checksum for response validation.
    **request_kwargs : Any
        Additional request arguments.

    Returns
    -------
    requests.Response
        HTTP response.
    """
    return self._request(
        method="GET",
        path=path,
        enable_cache=enable_cache,
        refresh_cache=refresh_cache,
        use_api_key=use_api_key,
        md5_checksum=md5_checksum,
        **request_kwargs,
    )

post

post(path: str, *, use_api_key: bool = True, **request_kwargs: Any) -> Response

Send a POST request.

PARAMETER	DESCRIPTION
path	API path relative to the base URL. TYPE: str
use_api_key	Whether to include the API key. TYPE: bool DEFAULT: True
**request_kwargs	Additional request arguments. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
Response	HTTP response.

Source code in openml/_api/clients/http.py

def post(
    self,
    path: str,
    *,
    use_api_key: bool = True,
    **request_kwargs: Any,
) -> Response:
    """
    Send a POST request.

    Parameters
    ----------
    path : str
        API path relative to the base URL.
    use_api_key : bool, optional
        Whether to include the API key.
    **request_kwargs : Any
        Additional request arguments.

    Returns
    -------
    requests.Response
        HTTP response.
    """
    return self._request(
        method="POST",
        path=path,
        enable_cache=False,
        use_api_key=use_api_key,
        **request_kwargs,
    )

MinIOClient

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.

ATTRIBUTE	DESCRIPTION
path	Configured base path for storage operations. TYPE: Path or None
headers	Default HTTP headers, including a user-agent identifying the OpenML Python client version. TYPE: dict of str to str

ResourceAPI

ResourceAPI(http: HTTPClient, minio: MinIOClient)

Bases: 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.

PARAMETER	DESCRIPTION
http	Configured HTTP client used for communication with the OpenML API. TYPE: HTTPClient
minio	Configured MinIO client used for object storage operations. TYPE: MinIOClient

ATTRIBUTE	DESCRIPTION
api_version	API version implemented by the resource. TYPE: APIVersion
resource_type	Type of OpenML resource handled by the implementation. TYPE: ResourceType
_http	Internal HTTP client instance. TYPE: HTTPClient
_minio	Internal MinIO client instance, if provided. TYPE: MinIOClient or None

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete abstractmethod

delete(resource_id: int) -> bool

Delete a resource by its identifier.

PARAMETER	DESCRIPTION
resource_id	Unique identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the deletion was successful.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

publish abstractmethod

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource to the OpenML server.

PARAMETER	DESCRIPTION
path	API endpoint path used for publishing the resource. TYPE: str
files	Files or payload data required for publishing. The structure depends on the resource type. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

tag abstractmethod

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

untag abstractmethod

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

ResourceV1API

ResourceV1API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceAPI

Version 1 implementation of the OpenML resource API.

This class provides XML-based implementations for publishing, deleting, tagging, and untagging resources using the V1 API endpoints. Responses are parsed using xmltodict.

Notes

V1 endpoints expect and return XML. Error handling follows the legacy OpenML server behavior and maps specific error codes to more descriptive exceptions where appropriate.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete

delete(resource_id: int) -> bool

Delete a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the server confirms successful deletion.

RAISES	DESCRIPTION
ValueError	If the resource type is not supported for deletion.
OpenMLNotAuthorizedError	If the user is not permitted to delete the resource.
OpenMLServerError	If deletion fails for an unknown reason.
OpenMLServerException	For other server-side errors.

Source code in openml/_api/resources/base/versions.py

def delete(self, resource_id: int) -> bool:
    """
    Delete a resource using the V1 API.

    Parameters
    ----------
    resource_id : int
        Identifier of the resource to delete.

    Returns
    -------
    bool
        ``True`` if the server confirms successful deletion.

    Raises
    ------
    ValueError
        If the resource type is not supported for deletion.
    OpenMLNotAuthorizedError
        If the user is not permitted to delete the resource.
    OpenMLServerError
        If deletion fails for an unknown reason.
    OpenMLServerException
        For other server-side errors.
    """
    if self.resource_type not in _LEGAL_RESOURCES_DELETE:
        raise ValueError(f"Can't delete a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/{resource_id}"
    try:
        response = self._http.delete(path)
        result = xmltodict.parse(response.content)
        return f"oml:{endpoint_name}_delete" in result
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

publish

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource using the V1 API.

PARAMETER	DESCRIPTION
path	API endpoint path for the upload. TYPE: str
files	Files to upload as part of the request payload. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

RAISES	DESCRIPTION
ValueError	If the server response does not contain a valid resource ID.
OpenMLServerException	If the server returns an error during upload.

Source code in openml/_api/resources/base/versions.py

def publish(self, path: str, files: Mapping[str, Any] | None) -> int:
    """
    Publish a new resource using the V1 API.

    Parameters
    ----------
    path : str
        API endpoint path for the upload.
    files : Mapping of str to Any or None
        Files to upload as part of the request payload.

    Returns
    -------
    int
        Identifier of the newly created resource.

    Raises
    ------
    ValueError
        If the server response does not contain a valid resource ID.
    OpenMLServerException
        If the server returns an error during upload.
    """
    response = self._http.post(path, files=files)
    parsed_response = xmltodict.parse(response.content)
    return self._extract_id_from_upload(parsed_response)

tag

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def tag(self, resource_id: int, tag: str) -> list[str]:
    """
    Add a tag to a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't tag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/tag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_tag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

untag

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def untag(self, resource_id: int, tag: str) -> list[str]:
    """
    Remove a tag from a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't untag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/untag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_untag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

ResourceV2API

ResourceV2API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceAPI

Version 2 implementation of the OpenML resource API.

This class represents the V2 API for resources. Operations such as publishing, deleting, tagging, and untagging are currently not supported and will raise OpenMLNotSupportedError.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

RunAPI

RunAPI(http: HTTPClient, minio: MinIOClient)

Bases: ResourceAPI

Abstract API interface for run resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete abstractmethod

delete(resource_id: int) -> bool

Delete a resource by its identifier.

PARAMETER	DESCRIPTION
resource_id	Unique identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the deletion was successful.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

publish abstractmethod

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource to the OpenML server.

PARAMETER	DESCRIPTION
path	API endpoint path used for publishing the resource. TYPE: str
files	Files or payload data required for publishing. The structure depends on the resource type. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

tag abstractmethod

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

untag abstractmethod

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

RunV1API

RunV1API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV1API, RunAPI

Version 1 API implementation for run resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete

delete(resource_id: int) -> bool

Delete a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the server confirms successful deletion.

RAISES	DESCRIPTION
ValueError	If the resource type is not supported for deletion.
OpenMLNotAuthorizedError	If the user is not permitted to delete the resource.
OpenMLServerError	If deletion fails for an unknown reason.
OpenMLServerException	For other server-side errors.

Source code in openml/_api/resources/base/versions.py

def delete(self, resource_id: int) -> bool:
    """
    Delete a resource using the V1 API.

    Parameters
    ----------
    resource_id : int
        Identifier of the resource to delete.

    Returns
    -------
    bool
        ``True`` if the server confirms successful deletion.

    Raises
    ------
    ValueError
        If the resource type is not supported for deletion.
    OpenMLNotAuthorizedError
        If the user is not permitted to delete the resource.
    OpenMLServerError
        If deletion fails for an unknown reason.
    OpenMLServerException
        For other server-side errors.
    """
    if self.resource_type not in _LEGAL_RESOURCES_DELETE:
        raise ValueError(f"Can't delete a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/{resource_id}"
    try:
        response = self._http.delete(path)
        result = xmltodict.parse(response.content)
        return f"oml:{endpoint_name}_delete" in result
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

publish

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource using the V1 API.

PARAMETER	DESCRIPTION
path	API endpoint path for the upload. TYPE: str
files	Files to upload as part of the request payload. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

RAISES	DESCRIPTION
ValueError	If the server response does not contain a valid resource ID.
OpenMLServerException	If the server returns an error during upload.

Source code in openml/_api/resources/base/versions.py

def publish(self, path: str, files: Mapping[str, Any] | None) -> int:
    """
    Publish a new resource using the V1 API.

    Parameters
    ----------
    path : str
        API endpoint path for the upload.
    files : Mapping of str to Any or None
        Files to upload as part of the request payload.

    Returns
    -------
    int
        Identifier of the newly created resource.

    Raises
    ------
    ValueError
        If the server response does not contain a valid resource ID.
    OpenMLServerException
        If the server returns an error during upload.
    """
    response = self._http.post(path, files=files)
    parsed_response = xmltodict.parse(response.content)
    return self._extract_id_from_upload(parsed_response)

tag

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def tag(self, resource_id: int, tag: str) -> list[str]:
    """
    Add a tag to a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't tag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/tag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_tag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

untag

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def untag(self, resource_id: int, tag: str) -> list[str]:
    """
    Remove a tag from a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't untag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/untag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_untag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

RunV2API

RunV2API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV2API, RunAPI

Version 2 API implementation for run resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

SetupAPI

SetupAPI(http: HTTPClient, minio: MinIOClient)

Bases: ResourceAPI

Abstract API interface for setup resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete abstractmethod

delete(resource_id: int) -> bool

Delete a resource by its identifier.

PARAMETER	DESCRIPTION
resource_id	Unique identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the deletion was successful.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

publish abstractmethod

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource to the OpenML server.

PARAMETER	DESCRIPTION
path	API endpoint path used for publishing the resource. TYPE: str
files	Files or payload data required for publishing. The structure depends on the resource type. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

tag abstractmethod

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

untag abstractmethod

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

SetupV1API

SetupV1API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV1API, SetupAPI

V1 XML API implementation for setups.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete

delete(resource_id: int) -> bool

Delete a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the server confirms successful deletion.

RAISES	DESCRIPTION
ValueError	If the resource type is not supported for deletion.
OpenMLNotAuthorizedError	If the user is not permitted to delete the resource.
OpenMLServerError	If deletion fails for an unknown reason.
OpenMLServerException	For other server-side errors.

Source code in openml/_api/resources/base/versions.py

def delete(self, resource_id: int) -> bool:
    """
    Delete a resource using the V1 API.

    Parameters
    ----------
    resource_id : int
        Identifier of the resource to delete.

    Returns
    -------
    bool
        ``True`` if the server confirms successful deletion.

    Raises
    ------
    ValueError
        If the resource type is not supported for deletion.
    OpenMLNotAuthorizedError
        If the user is not permitted to delete the resource.
    OpenMLServerError
        If deletion fails for an unknown reason.
    OpenMLServerException
        For other server-side errors.
    """
    if self.resource_type not in _LEGAL_RESOURCES_DELETE:
        raise ValueError(f"Can't delete a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/{resource_id}"
    try:
        response = self._http.delete(path)
        result = xmltodict.parse(response.content)
        return f"oml:{endpoint_name}_delete" in result
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

exists

exists(flow: OpenMLFlow, param_settings: list[dict[str, Any]]) -> int | bool

Checks whether a hyperparameter configuration already exists on the server.

PARAMETER	DESCRIPTION
flow	The openml flow object. Should have flow id present for the main flow and all subflows (i.e., it should be downloaded from the server by means of flow.get, and not instantiated locally) TYPE: OpenMLFlow
list	A list of dicts, where each dict has the following entries: oml:name : str: The OpenML parameter name oml:value : mixed: A representation of the parameter value oml:component : int: flow id to which the parameter belongs

RETURNS	DESCRIPTION
setup_id	setup id iff exists, False otherwise TYPE: int

Source code in openml/_api/resources/setup.py

def exists(
    self,
    flow: OpenMLFlow,
    param_settings: builtins.list[dict[str, Any]],
) -> int | bool:
    """
    Checks whether a hyperparameter configuration already exists on the server.

    Parameters
    ----------
    flow : OpenMLFlow
        The openml flow object. Should have flow id present for the main flow
        and all subflows (i.e., it should be downloaded from the server by
        means of flow.get, and not instantiated locally)

    list :
        A list of dicts, where each dict has the following entries:
            oml:name : str: The OpenML parameter name
            oml:value : mixed: A representation of the parameter value
            oml:component : int: flow id to which the parameter belongs

    Returns
    -------
    setup_id : int
        setup id iff exists, False otherwise
    """
    if flow.flow_id is None:
        raise ValueError("Flow must have a flow_id")
    description = xmltodict.unparse(
        SetupV1API._to_dict(flow.flow_id, param_settings), pretty=True
    )
    file_elements = {
        "description": ("description.arff", description),
    }

    api_call = "setup/exists/"
    setup_response = self._http.post(api_call, files=file_elements)
    xml_content = setup_response.text
    result_dict = xmltodict.parse(xml_content)

    setup_id = int(result_dict["oml:setup_exists"]["oml:id"])
    return setup_id if setup_id > 0 else False

get

get(setup_id: int) -> OpenMLSetup

Downloads the setup (configuration) description from OpenML and returns a structured object

PARAMETER	DESCRIPTION
setup_id	The Openml setup_id TYPE: int

RETURNS	DESCRIPTION
OpenMLSetup	An initialized OpenMLSetup object parsed from the XML

Source code in openml/_api/resources/setup.py

def get(self, setup_id: int) -> OpenMLSetup:
    """
    Downloads the setup (configuration) description from OpenML
    and returns a structured object

    Parameters
    ----------
    setup_id : int
        The Openml setup_id

    Returns
    -------
    OpenMLSetup
        An initialized OpenMLSetup object parsed from the XML
    """
    url_suffix = f"setup/{setup_id}"
    setup_response = self._http.get(url_suffix, enable_cache=True)
    xml_content = setup_response.text
    result_dict = xmltodict.parse(xml_content)

    return SetupV1API._create_setup(result_dict)

list

list(limit: int, offset: int, *, setup: Iterable[int] | None = None, flow: int | None = None, tag: str | None = None) -> list[OpenMLSetup]

Perform API call /setup/list/{filters}

PARAMETER	DESCRIPTION
The
filters
limit	TYPE: int
offset	TYPE: int
setup	TYPE: list(int) DEFAULT: None
flow	TYPE: int DEFAULT: None
tag	TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
list	setups that match the filters, going from id to the OpenMLSetup object.

Source code in openml/_api/resources/setup.py

def list(
    self,
    limit: int,
    offset: int,
    *,
    setup: Iterable[int] | None = None,
    flow: int | None = None,
    tag: str | None = None,
) -> builtins.list[OpenMLSetup]:
    """Perform API call `/setup/list/{filters}`

    Parameters
    ----------
    The setup argument that is a list is separated from the single value
    filters which are put into the kwargs.

    limit : int
    offset : int
    setup : list(int), optional
    flow : int, optional
    tag : str, optional

    Returns
    -------
    list
        setups that match the filters, going from id to the OpenMLSetup object.
    """
    api_call = SetupV1API._build_url(limit, offset, setup=setup, flow=flow, tag=tag)
    setup_response = self._http.get(api_call)
    xml_content = setup_response.text

    return SetupV1API._parse_list_xml(xml_content)

publish

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource using the V1 API.

PARAMETER	DESCRIPTION
path	API endpoint path for the upload. TYPE: str
files	Files to upload as part of the request payload. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

RAISES	DESCRIPTION
ValueError	If the server response does not contain a valid resource ID.
OpenMLServerException	If the server returns an error during upload.

Source code in openml/_api/resources/base/versions.py

def publish(self, path: str, files: Mapping[str, Any] | None) -> int:
    """
    Publish a new resource using the V1 API.

    Parameters
    ----------
    path : str
        API endpoint path for the upload.
    files : Mapping of str to Any or None
        Files to upload as part of the request payload.

    Returns
    -------
    int
        Identifier of the newly created resource.

    Raises
    ------
    ValueError
        If the server response does not contain a valid resource ID.
    OpenMLServerException
        If the server returns an error during upload.
    """
    response = self._http.post(path, files=files)
    parsed_response = xmltodict.parse(response.content)
    return self._extract_id_from_upload(parsed_response)

tag

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def tag(self, resource_id: int, tag: str) -> list[str]:
    """
    Add a tag to a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't tag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/tag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_tag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

untag

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def untag(self, resource_id: int, tag: str) -> list[str]:
    """
    Remove a tag from a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't untag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/untag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_untag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

SetupV2API

SetupV2API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV2API, SetupAPI

V2 JSoN API implementation for setups.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

StudyAPI

StudyAPI(http: HTTPClient, minio: MinIOClient)

Bases: ResourceAPI

Abstract API interface for study resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete abstractmethod

delete(resource_id: int) -> bool

Delete a resource by its identifier.

PARAMETER	DESCRIPTION
resource_id	Unique identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the deletion was successful.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

publish abstractmethod

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource to the OpenML server.

PARAMETER	DESCRIPTION
path	API endpoint path used for publishing the resource. TYPE: str
files	Files or payload data required for publishing. The structure depends on the resource type. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

tag abstractmethod

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

untag abstractmethod

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

StudyV1API

StudyV1API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV1API, StudyAPI

Version 1 API implementation for study resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete

delete(resource_id: int) -> bool

Delete a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the server confirms successful deletion.

RAISES	DESCRIPTION
ValueError	If the resource type is not supported for deletion.
OpenMLNotAuthorizedError	If the user is not permitted to delete the resource.
OpenMLServerError	If deletion fails for an unknown reason.
OpenMLServerException	For other server-side errors.

Source code in openml/_api/resources/base/versions.py

def delete(self, resource_id: int) -> bool:
    """
    Delete a resource using the V1 API.

    Parameters
    ----------
    resource_id : int
        Identifier of the resource to delete.

    Returns
    -------
    bool
        ``True`` if the server confirms successful deletion.

    Raises
    ------
    ValueError
        If the resource type is not supported for deletion.
    OpenMLNotAuthorizedError
        If the user is not permitted to delete the resource.
    OpenMLServerError
        If deletion fails for an unknown reason.
    OpenMLServerException
        For other server-side errors.
    """
    if self.resource_type not in _LEGAL_RESOURCES_DELETE:
        raise ValueError(f"Can't delete a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/{resource_id}"
    try:
        response = self._http.delete(path)
        result = xmltodict.parse(response.content)
        return f"oml:{endpoint_name}_delete" in result
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

publish

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource using the V1 API.

PARAMETER	DESCRIPTION
path	API endpoint path for the upload. TYPE: str
files	Files to upload as part of the request payload. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

RAISES	DESCRIPTION
ValueError	If the server response does not contain a valid resource ID.
OpenMLServerException	If the server returns an error during upload.

Source code in openml/_api/resources/base/versions.py

def publish(self, path: str, files: Mapping[str, Any] | None) -> int:
    """
    Publish a new resource using the V1 API.

    Parameters
    ----------
    path : str
        API endpoint path for the upload.
    files : Mapping of str to Any or None
        Files to upload as part of the request payload.

    Returns
    -------
    int
        Identifier of the newly created resource.

    Raises
    ------
    ValueError
        If the server response does not contain a valid resource ID.
    OpenMLServerException
        If the server returns an error during upload.
    """
    response = self._http.post(path, files=files)
    parsed_response = xmltodict.parse(response.content)
    return self._extract_id_from_upload(parsed_response)

tag

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def tag(self, resource_id: int, tag: str) -> list[str]:
    """
    Add a tag to a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't tag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/tag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_tag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

untag

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def untag(self, resource_id: int, tag: str) -> list[str]:
    """
    Remove a tag from a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't untag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/untag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_untag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

StudyV2API

StudyV2API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV2API, StudyAPI

Version 2 API implementation for study resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

TaskAPI

TaskAPI(http: HTTPClient, minio: MinIOClient)

Bases: ResourceAPI

Abstract API interface for task resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete abstractmethod

delete(resource_id: int) -> bool

Delete a resource by its identifier.

PARAMETER	DESCRIPTION
resource_id	Unique identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the deletion was successful.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

publish abstractmethod

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource to the OpenML server.

PARAMETER	DESCRIPTION
path	API endpoint path used for publishing the resource. TYPE: str
files	Files or payload data required for publishing. The structure depends on the resource type. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

tag abstractmethod

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

untag abstractmethod

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

Notes

Concrete subclasses must implement this method.

Source code in openml/_api/resources/base/base.py

@abstractmethod
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.
    """

TaskV1API

TaskV1API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV1API, TaskAPI

Version 1 API implementation for task resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

delete

delete(resource_id: int) -> bool

Delete a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the server confirms successful deletion.

RAISES	DESCRIPTION
ValueError	If the resource type is not supported for deletion.
OpenMLNotAuthorizedError	If the user is not permitted to delete the resource.
OpenMLServerError	If deletion fails for an unknown reason.
OpenMLServerException	For other server-side errors.

Source code in openml/_api/resources/base/versions.py

def delete(self, resource_id: int) -> bool:
    """
    Delete a resource using the V1 API.

    Parameters
    ----------
    resource_id : int
        Identifier of the resource to delete.

    Returns
    -------
    bool
        ``True`` if the server confirms successful deletion.

    Raises
    ------
    ValueError
        If the resource type is not supported for deletion.
    OpenMLNotAuthorizedError
        If the user is not permitted to delete the resource.
    OpenMLServerError
        If deletion fails for an unknown reason.
    OpenMLServerException
        For other server-side errors.
    """
    if self.resource_type not in _LEGAL_RESOURCES_DELETE:
        raise ValueError(f"Can't delete a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/{resource_id}"
    try:
        response = self._http.delete(path)
        result = xmltodict.parse(response.content)
        return f"oml:{endpoint_name}_delete" in result
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

publish

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource using the V1 API.

PARAMETER	DESCRIPTION
path	API endpoint path for the upload. TYPE: str
files	Files to upload as part of the request payload. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

RAISES	DESCRIPTION
ValueError	If the server response does not contain a valid resource ID.
OpenMLServerException	If the server returns an error during upload.

Source code in openml/_api/resources/base/versions.py

def publish(self, path: str, files: Mapping[str, Any] | None) -> int:
    """
    Publish a new resource using the V1 API.

    Parameters
    ----------
    path : str
        API endpoint path for the upload.
    files : Mapping of str to Any or None
        Files to upload as part of the request payload.

    Returns
    -------
    int
        Identifier of the newly created resource.

    Raises
    ------
    ValueError
        If the server response does not contain a valid resource ID.
    OpenMLServerException
        If the server returns an error during upload.
    """
    response = self._http.post(path, files=files)
    parsed_response = xmltodict.parse(response.content)
    return self._extract_id_from_upload(parsed_response)

tag

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def tag(self, resource_id: int, tag: str) -> list[str]:
    """
    Add a tag to a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't tag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/tag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_tag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

untag

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def untag(self, resource_id: int, tag: str) -> list[str]:
    """
    Remove a tag from a resource using the V1 API.

    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.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't untag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/untag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    result = parsed_response[f"oml:{endpoint_name}_untag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

TaskV2API

TaskV2API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV2API, TaskAPI

Version 2 API implementation for task resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio