resources

openml._api.resources

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

add_topic

add_topic(dataset_id: int, topic: str) -> int

Adds a topic to a dataset. This API is not available for all OpenML users and is accessible only by admins.

PARAMETER	DESCRIPTION
dataset_id	id of the dataset to be forked TYPE: int
topic	Topic to be added TYPE: str

RETURNS	DESCRIPTION
Dataset id

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

def add_topic(self, dataset_id: int, topic: str) -> int:
    """
    Adds a topic to a dataset.
    This API is not available for all OpenML users and is accessible only by admins.

    Parameters
    ----------
    dataset_id : int
        id of the dataset to be forked
    topic : str
        Topic to be added

    Returns
    -------
    Dataset id
    """
    form_data = {"data_id": dataset_id, "topic": topic}  # type: dict[str, str | int]
    result_xml = self._http.post("data/topicadd", data=form_data).text
    result = xmltodict.parse(result_xml)
    dataset_id = result["oml:data_topic"]["oml:id"]
    return int(dataset_id)

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)
        try:
            parsed_response = xmltodict.parse(response.content)
        except xml.parsers.expat.ExpatError as e:
            msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
            raise OpenMLServerError(msg) from e
        return f"oml:{endpoint_name}_delete" in parsed_response
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

delete_topic

delete_topic(dataset_id: int, topic: str) -> int

Removes a topic from a dataset. This API is not available for all OpenML users and is accessible only by admins.

PARAMETER	DESCRIPTION
dataset_id	id of the dataset to be forked TYPE: int
topic	Topic to be deleted TYPE: str

RETURNS	DESCRIPTION
Dataset id

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

def delete_topic(self, dataset_id: int, topic: str) -> int:
    """
    Removes a topic from a dataset.
    This API is not available for all OpenML users and is accessible only by admins.

    Parameters
    ----------
    dataset_id : int
        id of the dataset to be forked
    topic : str
        Topic to be deleted

    Returns
    -------
    Dataset id
    """
    form_data = {"data_id": dataset_id, "topic": topic}  # type: dict[str, str | int]
    result_xml = self._http.post("data/topicdelete", data=form_data).text
    result = xmltodict.parse(result_xml)
    dataset_id = result["oml:data_topic"]["oml:id"]
    return int(dataset_id)

download_dataset_arff

download_dataset_arff(description: dict | OpenMLDataset) -> Path

Download dataset arff file.

PARAMETER	DESCRIPTION
description	Either a dataset description as dict or OpenMLDataset. TYPE: dictionary or OpenMLDataset

RETURNS	DESCRIPTION
output_filename	Location of ARFF file. TYPE: Path

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

def download_dataset_arff(
    self,
    description: dict | OpenMLDataset,
) -> Path:
    """Download dataset arff file.

    Parameters
    ----------
    description : dictionary or OpenMLDataset
        Either a dataset description as dict or OpenMLDataset.

    Returns
    -------
    output_filename : Path
        Location of ARFF file.
    """
    if isinstance(description, dict):
        md5_checksum_fixture = description.get("oml:md5_checksum")
        url = str(description["oml:url"])
        did = int(description.get("oml:id"))  # type: ignore
    elif isinstance(description, OpenMLDataset):
        md5_checksum_fixture = description.md5_checksum
        assert description.url is not None
        assert description.dataset_id is not None

        url = description.url
        did = int(description.dataset_id)
    else:
        raise TypeError("`description` should be either OpenMLDataset or Dict.")

    try:
        # save the file in cache and get it's path
        self._http.get(url, enable_cache=True, md5_checksum=md5_checksum_fixture)
        output_file_path = self._http.cache_path_from_url(url)
    except OpenMLHashException as e:
        additional_info = f" Raised when downloading dataset {did}."
        e.args = (e.args[0] + additional_info,)
        raise e

    return output_file_path

download_dataset_parquet

download_dataset_parquet(description: dict | OpenMLDataset, download_all_files: bool = False) -> Path | None

Download dataset parquet file.

PARAMETER	DESCRIPTION
description	Either a dataset description as dict or OpenMLDataset. TYPE: dictionary or OpenMLDataset
download_all_files	If True, download all data found in the bucket to which the description's parquet_url points, only download the parquet file otherwise. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Path | None

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

def download_dataset_parquet(
    self,
    description: dict | OpenMLDataset,
    download_all_files: bool = False,  # noqa: FBT002
) -> Path | None:
    """Download dataset parquet file.

    Parameters
    ----------
    description : dictionary or OpenMLDataset
        Either a dataset description as dict or OpenMLDataset.
    download_all_files: bool, optional (default=False)
        If `True`, download all data found in the bucket to which the description's
        ``parquet_url`` points, only download the parquet file otherwise.

    Returns
    -------
    Path | None
    """
    if isinstance(description, dict):
        url = str(description.get("oml:parquet_url"))
    elif isinstance(description, OpenMLDataset):
        url = str(description._parquet_url)
        assert description.dataset_id is not None
    else:
        raise TypeError("`description` should be either OpenMLDataset or Dict.")

    output_file_path = Path(openml.config.get_minio_download_path(url))
    if download_all_files:
        self._minio.download_minio_bucket(source=url)

    if not output_file_path.is_file():
        try:
            output_file_path = self._minio.download_minio_file(
                source=url,
            )
        except (
            FileNotFoundError,
            urllib3.exceptions.MaxRetryError,
            minio.error.ServerError,
        ) as e:
            logger.warning(f"Could not download file from {url}: {e}")
            return None
    return output_file_path

download_features_file

download_features_file(dataset_id: int) -> Path

Download features file.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int

RETURNS	DESCRIPTION
Path

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

def download_features_file(self, dataset_id: int) -> Path:
    """Download features file.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.

    Returns
    -------
    Path
    """
    path = f"data/features/{dataset_id}"
    file = self._download_file(path)
    self.parse_features_file(file)
    return file

download_qualities_file

download_qualities_file(dataset_id: int) -> Path | None

Download qualities file.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int

RETURNS	DESCRIPTION
Path

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

def download_qualities_file(self, dataset_id: int) -> Path | None:
    """Download qualities file.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.

    Returns
    -------
    Path
    """
    path = f"data/qualities/{dataset_id}"
    try:
        file = self._download_file(path)
    except OpenMLServerException as e:
        if e.code == 362 and str(e) == "No qualities found - None":
            # quality file stays as None
            logger.warning(f"No qualities found for dataset {dataset_id}")
            return None
        raise e

    self.parse_qualities_file(file)
    return file

edit

edit(dataset_id: int, *, description: str | None = None, creator: str | None = None, contributor: str | None = None, collection_date: str | None = None, language: str | None = None, default_target_attribute: str | None = None, ignore_attribute: str | list[str] | None = None, citation: str | None = None, row_id_attribute: str | None = None, original_data_url: str | None = None, paper_url: str | None = None) -> int

Edits an OpenMLDataset.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int
description	Description of the dataset. TYPE: str DEFAULT: None
creator	The person who created the dataset. TYPE: str DEFAULT: None
contributor	People who contributed to the current version of the dataset. TYPE: str DEFAULT: None
collection_date	The date the data was originally collected, given by the uploader. TYPE: str DEFAULT: None
language	Language in which the data is represented. Starts with 1 upper case letter, rest lower case, e.g. 'English'. TYPE: str DEFAULT: None
default_target_attribute	The default target attribute, if it exists. Can have multiple values, comma separated. TYPE: str DEFAULT: None
ignore_attribute	Attributes that should be excluded in modelling, such as identifiers and indexes. TYPE: str | list DEFAULT: None
citation	Reference(s) that should be cited when building on this data. TYPE: str DEFAULT: None
row_id_attribute	The attribute that represents the row-id column, if present in the dataset. If data is a dataframe and row_id_attribute is not specified, the index of the dataframe will be used as the row_id_attribute. If the name of the index is None, it will be discarded. .. versionadded: 0.8 Inference of row_id_attribute from a dataframe. TYPE: str DEFAULT: None
original_data_url	For derived data, the url to the original dataset. TYPE: str DEFAULT: None
paper_url	Link to a paper describing the dataset. TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
Dataset id

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

def edit(
    self,
    dataset_id: int,
    *,
    description: str | None = None,
    creator: str | None = None,
    contributor: str | None = None,
    collection_date: str | None = None,
    language: str | None = None,
    default_target_attribute: str | None = None,
    ignore_attribute: str | builtins.list[str] | None = None,
    citation: str | None = None,
    row_id_attribute: str | None = None,
    original_data_url: str | None = None,
    paper_url: str | None = None,
) -> int:
    """Edits an OpenMLDataset.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.
    description : str, optional
        Description of the dataset.
    creator : str, optional
        The person who created the dataset.
    contributor : str, optional
        People who contributed to the current version of the dataset.
    collection_date : str, optional
        The date the data was originally collected, given by the uploader.
    language : str, optional
        Language in which the data is represented.
        Starts with 1 upper case letter, rest lower case, e.g. 'English'.
    default_target_attribute : str, optional
        The default target attribute, if it exists.
        Can have multiple values, comma separated.
    ignore_attribute : str | list, optional
        Attributes that should be excluded in modelling,
        such as identifiers and indexes.
    citation : str, optional
        Reference(s) that should be cited when building on this data.
    row_id_attribute : str, optional
        The attribute that represents the row-id column, if present in the
        dataset. If ``data`` is a dataframe and ``row_id_attribute`` is not
        specified, the index of the dataframe will be used as the
        ``row_id_attribute``. If the name of the index is ``None``, it will
        be discarded.

        .. versionadded: 0.8
            Inference of ``row_id_attribute`` from a dataframe.
    original_data_url : str, optional
        For derived data, the url to the original dataset.
    paper_url : str, optional
        Link to a paper describing the dataset.

    Returns
    -------
    Dataset id
    """
    # compose data edit parameters as xml
    form_data = {"data_id": dataset_id}  # type: dict[str, str | int]
    xml = OrderedDict()  # type: 'OrderedDict[str, OrderedDict]'
    xml["oml:data_edit_parameters"] = OrderedDict()
    xml["oml:data_edit_parameters"]["@xmlns:oml"] = "http://openml.org/openml"
    xml["oml:data_edit_parameters"]["oml:description"] = description
    xml["oml:data_edit_parameters"]["oml:creator"] = creator
    xml["oml:data_edit_parameters"]["oml:contributor"] = contributor
    xml["oml:data_edit_parameters"]["oml:collection_date"] = collection_date
    xml["oml:data_edit_parameters"]["oml:language"] = language
    xml["oml:data_edit_parameters"]["oml:default_target_attribute"] = default_target_attribute
    xml["oml:data_edit_parameters"]["oml:row_id_attribute"] = row_id_attribute
    xml["oml:data_edit_parameters"]["oml:ignore_attribute"] = ignore_attribute
    xml["oml:data_edit_parameters"]["oml:citation"] = citation
    xml["oml:data_edit_parameters"]["oml:original_data_url"] = original_data_url
    xml["oml:data_edit_parameters"]["oml:paper_url"] = paper_url

    # delete None inputs
    for k in list(xml["oml:data_edit_parameters"]):
        if not xml["oml:data_edit_parameters"][k]:
            del xml["oml:data_edit_parameters"][k]

    file_elements = {
        "edit_parameters": ("description.xml", xmltodict.unparse(xml)),
    }  # type: dict[str, str | tuple[str, str]]
    result_xml = self._http.post("data/edit", data=form_data, files=file_elements).text
    result = xmltodict.parse(result_xml)
    dataset_id = result["oml:data_edit"]["oml:id"]
    return int(dataset_id)

feature_add_ontology

feature_add_ontology(dataset_id: int, index: int, ontology: str) -> bool

An ontology describes the concept that are described in a feature. An ontology is defined by an URL where the information is provided. Adds an ontology (URL) to a given dataset feature (defined by a dataset id and index). The dataset has to exists on OpenML and needs to have been processed by the evaluation engine.

PARAMETER	DESCRIPTION
dataset_id	id of the dataset to which the feature belongs TYPE: int
index	index of the feature in dataset (0-based) TYPE: int
ontology	URL to ontology (max. 256 characters) TYPE: str

RETURNS	DESCRIPTION
True or throws an OpenML server exception

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

def feature_add_ontology(self, dataset_id: int, index: int, ontology: str) -> bool:
    """
    An ontology describes the concept that are described in a feature. An
    ontology is defined by an URL where the information is provided. Adds
    an ontology (URL) to a given dataset feature (defined by a dataset id
    and index). The dataset has to exists on OpenML and needs to have been
    processed by the evaluation engine.

    Parameters
    ----------
    dataset_id : int
        id of the dataset to which the feature belongs
    index : int
        index of the feature in dataset (0-based)
    ontology : str
        URL to ontology (max. 256 characters)

    Returns
    -------
    True or throws an OpenML server exception
    """
    upload_data: dict[str, int | str] = {
        "data_id": dataset_id,
        "index": index,
        "ontology": ontology,
    }
    self._http.post("data/feature/ontology/add", data=upload_data)
    # an error will be thrown in case the request was unsuccessful
    return True

feature_remove_ontology

feature_remove_ontology(dataset_id: int, index: int, ontology: str) -> bool

Removes an existing ontology (URL) from a given dataset feature (defined by a dataset id and index). The dataset has to exists on OpenML and needs to have been processed by the evaluation engine. Ontology needs to be attached to the specific fearure.

PARAMETER	DESCRIPTION
dataset_id	id of the dataset to which the feature belongs TYPE: int
index	index of the feature in dataset (0-based) TYPE: int
ontology	URL to ontology (max. 256 characters) TYPE: str

RETURNS	DESCRIPTION
True or throws an OpenML server exception

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

def feature_remove_ontology(self, dataset_id: int, index: int, ontology: str) -> bool:
    """
    Removes an existing ontology (URL) from a given dataset feature (defined
    by a dataset id and index). The dataset has to exists on OpenML and needs
    to have been processed by the evaluation engine. Ontology needs to be
    attached to the specific fearure.

    Parameters
    ----------
    dataset_id : int
        id of the dataset to which the feature belongs
    index : int
        index of the feature in dataset (0-based)
    ontology : str
        URL to ontology (max. 256 characters)

    Returns
    -------
    True or throws an OpenML server exception
    """
    upload_data: dict[str, int | str] = {
        "data_id": dataset_id,
        "index": index,
        "ontology": ontology,
    }
    self._http.post("data/feature/ontology/remove", data=upload_data)
    # an error will be thrown in case the request was unsuccessful
    return True

fork

fork(dataset_id: int) -> int

Creates a new dataset version, with the authenticated user as the new owner. The forked dataset can have distinct dataset meta-data, but the actual data itself is shared with the original version.

PARAMETER	DESCRIPTION
dataset_id	id of the dataset to be forked TYPE: int

RETURNS	DESCRIPTION
Dataset id of the forked dataset

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

def fork(self, dataset_id: int) -> int:
    """
    Creates a new dataset version, with the authenticated user as the new owner.
    The forked dataset can have distinct dataset meta-data,
    but the actual data itself is shared with the original version.

    Parameters
    ----------
    dataset_id : int
        id of the dataset to be forked

    Returns
    -------
    Dataset id of the forked dataset

    """
    # compose data fork parameters
    form_data = {"data_id": dataset_id}
    result_xml = self._http.post("data/fork", data=form_data).text
    result = xmltodict.parse(result_xml)
    dataset_id = result["oml:data_fork"]["oml:id"]
    return int(dataset_id)

get

get(dataset_id: int, *, download_data: bool = False, cache_format: Literal['pickle', 'feather'] = 'pickle', download_qualities: bool = False, download_features_meta_data: bool = False, download_all_files: bool = False, force_refresh_cache: bool = False) -> OpenMLDataset

Download the OpenML dataset representation, optionally also download actual data file.

PARAMETER	DESCRIPTION
dataset_id	Dataset ID (integer) or dataset name (string) of the dataset to download. TYPE: int or str
download_data	If True, download the data file. TYPE: bool(default=False) DEFAULT: False
cache_format	Format for caching the dataset - may be feather or pickle Note that the default 'pickle' option may load slower than feather when no.of.rows is very high. TYPE: str(default='pickle') in {'pickle', 'feather'} DEFAULT: 'pickle'
download_qualities	Option to download 'qualities' meta-data with the minimal dataset description. TYPE: bool(default=False) DEFAULT: False
download_features_meta_data	Option to download 'features' meta-data with the minimal dataset description. TYPE: bool(default=False) DEFAULT: False
download_all_files	EXPERIMENTAL. Download all files related to the dataset that reside on the server. TYPE: bool DEFAULT: False
force_refresh_cache	Force the cache to delete the cache directory and re-download the data. TYPE: bool(default=False) DEFAULT: False

RETURNS	DESCRIPTION
dataset	The downloaded dataset. TYPE: :class:`openml.OpenMLDataset`

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

def get(
    self,
    dataset_id: int,
    *,
    download_data: bool = False,
    cache_format: Literal["pickle", "feather"] = "pickle",
    download_qualities: bool = False,
    download_features_meta_data: bool = False,
    download_all_files: bool = False,
    force_refresh_cache: bool = False,
) -> OpenMLDataset:
    """Download the OpenML dataset representation, optionally also download actual data file.

    Parameters
    ----------
    dataset_id : int or str
        Dataset ID (integer) or dataset name (string) of the dataset to download.
    download_data : bool (default=False)
        If True, download the data file.
    cache_format : str (default='pickle') in {'pickle', 'feather'}
        Format for caching the dataset - may be feather or pickle
        Note that the default 'pickle' option may load slower than feather when
        no.of.rows is very high.
    download_qualities : bool (default=False)
        Option to download 'qualities' meta-data with the minimal dataset description.
    download_features_meta_data : bool (default=False)
        Option to download 'features' meta-data with the minimal dataset description.
    download_all_files: bool (default=False)
        EXPERIMENTAL. Download all files related to the dataset that reside on the server.
    force_refresh_cache : bool (default=False)
        Force the cache to delete the cache directory and re-download the data.

    Returns
    -------
    dataset : :class:`openml.OpenMLDataset`
        The downloaded dataset.
    """
    path = f"data/{dataset_id}"
    try:
        response = self._http.get(path, enable_cache=True, refresh_cache=force_refresh_cache)
        xml_content = response.text
        description = xmltodict.parse(xml_content)["oml:data_set_description"]

        features_file = None
        qualities_file = None

        if download_features_meta_data:
            features_file = self.download_features_file(dataset_id)
        if download_qualities:
            qualities_file = self.download_qualities_file(dataset_id)

        parquet_file = None
        skip_parquet = (
            os.environ.get(openml.config.OPENML_SKIP_PARQUET_ENV_VAR, "false").casefold()
            == "true"
        )
        download_parquet = "oml:parquet_url" in description and not skip_parquet
        if download_parquet and (download_data or download_all_files):
            try:
                parquet_file = self.download_dataset_parquet(
                    description,
                    download_all_files=download_all_files,
                )
            except urllib3.exceptions.MaxRetryError:
                parquet_file = None

        arff_file = None
        if parquet_file is None and download_data:
            if download_parquet:
                logger.warning("Failed to download parquet, fallback on ARFF.")
            arff_file = self.download_dataset_arff(description)
    except OpenMLServerException as e:
        # if there was an exception
        # check if the user had access to the dataset
        if e.code == NO_ACCESS_GRANTED_ERRCODE:
            raise OpenMLPrivateDatasetError(e.message) from None

        raise e

    return self._create_dataset_from_xml(
        description,
        features_file=features_file,
        qualities_file=qualities_file,
        arff_file=arff_file,
        parquet_file=parquet_file,
        cache_format=cache_format,
    )

get_features

get_features(dataset_id: int, force_refresh_cache: bool = False) -> dict[int, OpenMLDataFeature]

Get features of a dataset from server.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int
force_refresh_cache	Refresh the cache and re-download the features file. TYPE: bool(default=False) DEFAULT: False

RETURNS	DESCRIPTION
dict[int, OpenMLDataFeature]

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

def get_features(
    self,
    dataset_id: int,
    force_refresh_cache: bool = False,  # noqa: FBT002
) -> dict[int, OpenMLDataFeature]:
    """Get features of a dataset from server.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.
    force_refresh_cache : bool (default=False)
        Refresh the cache and re-download the features file.

    Returns
    -------
    dict[int, OpenMLDataFeature]
    """
    path = f"data/features/{dataset_id}"
    xml = self._http.get(path, enable_cache=True, refresh_cache=force_refresh_cache).text
    return self._parse_features_xml(xml)

get_online_dataset_format

get_online_dataset_format(dataset_id: int) -> str

Get the dataset format for a given dataset id from the OpenML website.

PARAMETER	DESCRIPTION
dataset_id	A dataset id. TYPE: int

RETURNS	DESCRIPTION
str	Dataset format.

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

def get_online_dataset_format(self, dataset_id: int) -> str:
    """Get the dataset format for a given dataset id from the OpenML website.

    Parameters
    ----------
    dataset_id : int
        A dataset id.

    Returns
    -------
    str
        Dataset format.
    """
    dataset_xml = self._http.get(f"data/{dataset_id}").text
    # build a dict from the xml and get the format from the dataset description
    return xmltodict.parse(dataset_xml)["oml:data_set_description"]["oml:format"].lower()  # type: ignore

get_qualities

get_qualities(dataset_id: int, force_refresh_cache: bool = False) -> dict[str, float] | None

Get qualities of a dataset from server.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int
force_refresh_cache	Refresh the cache and re-download the qualities file. TYPE: bool(default=False) DEFAULT: False

RETURNS	DESCRIPTION
dict[str, float] | None

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

def get_qualities(
    self,
    dataset_id: int,
    force_refresh_cache: bool = False,  # noqa: FBT002
) -> dict[str, float] | None:
    """Get qualities of a dataset from server.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.
    force_refresh_cache : bool (default=False)
        Refresh the cache and re-download the qualities file.

    Returns
    -------
    dict[str, float] | None
    """
    path = f"data/qualities/{dataset_id!s}"
    try:
        xml = self._http.get(path, enable_cache=True, refresh_cache=force_refresh_cache).text
    except OpenMLServerException as e:
        if e.code == 362 and str(e) == "No qualities found - None":
            # quality file stays as None
            logger.warning(f"No qualities found for dataset {dataset_id}")
            return None

        raise e
    return self._parse_qualities_xml(xml)

list

list(limit: int, offset: int, *, data_id: list[int] | None = None, **kwargs: Any) -> DataFrame

Perform api call to return a list of all datasets.

PARAMETER	DESCRIPTION
The
ones
display_errors
default
limit	The maximum number of datasets to show. TYPE: int
offset	The number of datasets to skip, starting from the first. TYPE: int
data_id	TYPE: list DEFAULT: None
kwargs	Legal filter operators (keys in the dict): tag, status, limit, offset, data_name, data_version, number_instances, number_features, number_classes, number_missing_values. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
datasets	TYPE: dataframe

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

def list(
    self,
    limit: int,
    offset: int,
    *,
    data_id: builtins.list[int] | None = None,
    **kwargs: Any,
) -> pd.DataFrame:
    """
    Perform api call to return a list of all datasets.

    Parameters
    ----------
    The arguments that are lists are separated from the single value
    ones which are put into the kwargs.
    display_errors is also separated from the kwargs since it has a
    default value.

    limit : int
        The maximum number of datasets to show.
    offset : int
        The number of datasets to skip, starting from the first.
    data_id : list, optional

    kwargs : dict, optional
        Legal filter operators (keys in the dict):
        tag, status, limit, offset, data_name, data_version, number_instances,
        number_features, number_classes, number_missing_values.

    Returns
    -------
    datasets : dataframe
    """
    api_call = "data/list"

    if limit is not None:
        api_call += f"/limit/{limit}"
    if offset is not None:
        api_call += f"/offset/{offset}"

    if kwargs is not None:
        for operator, value in kwargs.items():
            if value is not None:
                api_call += f"/{operator}/{value}"
    if data_id is not None:
        api_call += f"/data_id/{','.join([str(int(i)) for i in data_id])}"
    xml_string = self._http.get(api_call).text
    return self._parse_list_xml(xml_string)

list_qualities

list_qualities() -> list[str]

Return list of data qualities available.

The function performs an API call to retrieve the entire list of data qualities that are computed on the datasets uploaded.

RETURNS	DESCRIPTION
list

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

def list_qualities(self) -> builtins.list[str]:
    """Return list of data qualities available.

    The function performs an API call to retrieve the entire list of
    data qualities that are computed on the datasets uploaded.

    Returns
    -------
    list
    """
    api_call = "data/qualities/list"
    xml_string = self._http.get(api_call).text
    qualities = xmltodict.parse(xml_string, force_list=("oml:quality"))
    # Minimalistic check if the XML is useful
    if "oml:data_qualities_list" not in qualities:
        raise ValueError('Error in return XML, does not contain "oml:data_qualities_list"')

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

    return qualities["oml:data_qualities_list"]["oml:quality"]

parse_features_file

parse_features_file(features_file: Path, features_pickle_file: Path | None = None) -> dict[int, OpenMLDataFeature]

Parse features file (xml) and store it as a pickle file.

PARAMETER	DESCRIPTION
features_file	Path to features file. TYPE: Path
features_pickle_file	Path to pickle file for features. TYPE: Path DEFAULT: None

RETURNS	DESCRIPTION
features	TYPE: dict[int, OpenMLDataFeature]

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

def parse_features_file(
    self, features_file: Path, features_pickle_file: Path | None = None
) -> dict[int, OpenMLDataFeature]:
    """
    Parse features file (xml) and store it as a pickle file.

    Parameters
    ----------
    features_file : Path
        Path to features file.
    features_pickle_file : Path, optional
        Path to pickle file for features.

    Returns
    -------
    features : dict[int, OpenMLDataFeature]
    """
    if features_pickle_file is None:
        features_pickle_file = features_file.with_suffix(features_file.suffix + ".pkl")
    assert features_file.suffix == ".xml"

    with Path(features_file).open("r", encoding="utf8") as fh:
        features_xml = fh.read()

    features = self._parse_features_xml(features_xml)

    with features_pickle_file.open("wb") as fh_binary:
        pickle.dump(features, fh_binary)

    return features

parse_qualities_file

parse_qualities_file(qualities_file: Path, qualities_pickle_file: Path | None = None) -> dict[str, float]

Parse qualities file (xml) and store it as a pickle file.

PARAMETER	DESCRIPTION
qualities_file	Path to qualities file. TYPE: Path
qualities_pickle_file	Path to pickle file for qualities. TYPE: Path DEFAULT: None

RETURNS	DESCRIPTION
qualities	TYPE: dict[str, float]

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

def parse_qualities_file(
    self, qualities_file: Path, qualities_pickle_file: Path | None = None
) -> dict[str, float]:
    """Parse qualities file (xml) and store it as a pickle file.

    Parameters
    ----------
    qualities_file : Path
        Path to qualities file.
    qualities_pickle_file : Path, optional
        Path to pickle file for qualities.

    Returns
    -------
    qualities : dict[str, float]
    """
    if qualities_pickle_file is None:
        qualities_pickle_file = qualities_file.with_suffix(qualities_file.suffix + ".pkl")
    assert qualities_file.suffix == ".xml"

    with Path(qualities_file).open("r", encoding="utf8") as fh:
        qualities_xml = fh.read()

    qualities = self._parse_qualities_xml(qualities_xml)

    with qualities_pickle_file.open("wb") as fh_binary:
        pickle.dump(qualities, fh_binary)

    return qualities

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)
    try:
        parsed_response = xmltodict.parse(response.content)
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    return self._extract_id_from_upload(parsed_response)

status_update

status_update(dataset_id: int, status: Literal['active', 'deactivated']) -> None

Updates the status of a dataset to either 'active' or 'deactivated'. Please see the OpenML API documentation for a description of the status and all legal status transitions: docs.openml.org/concepts/data/#dataset-status

PARAMETER	DESCRIPTION
dataset_id	The data id of the dataset TYPE: int
status	'active' or 'deactivated' TYPE: (str,)

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

def status_update(self, dataset_id: int, status: Literal["active", "deactivated"]) -> None:
    """
    Updates the status of a dataset to either 'active' or 'deactivated'.
    Please see the OpenML API documentation for a description of the status
    and all legal status transitions:
    https://docs.openml.org/concepts/data/#dataset-status

    Parameters
    ----------
    dataset_id : int
        The data id of the dataset
    status : str,
        'active' or 'deactivated'
    """
    legal_status = {"active", "deactivated"}
    if status not in legal_status:
        raise ValueError(f"Illegal status value. Legal values: {legal_status}")

    data: dict[str, str | int] = {"data_id": dataset_id, "status": status}
    result_xml = self._http.post("data/status/update", data=data).text
    result = xmltodict.parse(result_xml)
    server_data_id = result["oml:data_status_update"]["oml:id"]
    server_status = result["oml:data_status_update"]["oml:status"]
    if status != server_status or int(dataset_id) != int(server_data_id):
        # This should never happen
        raise ValueError("Data id/status does not match")

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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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

download_dataset_arff

download_dataset_arff(description: dict | OpenMLDataset) -> Path

Download dataset arff file.

PARAMETER	DESCRIPTION
description	Either a dataset description as dict or OpenMLDataset. TYPE: dictionary or OpenMLDataset

RETURNS	DESCRIPTION
output_filename	Location of ARFF file. TYPE: Path

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

def download_dataset_arff(
    self,
    description: dict | OpenMLDataset,
) -> Path:
    """Download dataset arff file.

    Parameters
    ----------
    description : dictionary or OpenMLDataset
        Either a dataset description as dict or OpenMLDataset.

    Returns
    -------
    output_filename : Path
        Location of ARFF file.
    """
    if isinstance(description, dict):
        url = str(description["url"])
        did = int(description.get("id"))  # type: ignore
        md5_checksum_fixture = description.get("md5_checksum")
    elif isinstance(description, OpenMLDataset):
        assert description.url is not None
        assert description.dataset_id is not None
        md5_checksum_fixture = description.md5_checksum

        url = description.url
        did = int(description.dataset_id)
    else:
        raise TypeError("`description` should be either OpenMLDataset or Dict.")

    try:
        # save the file in cache and get it's path
        self._http.get(url, enable_cache=True, md5_checksum=md5_checksum_fixture)
        output_file_path = self._http.cache_path_from_url(url)
    except OpenMLHashException as e:
        additional_info = f" Raised when downloading dataset {did}."
        e.args = (e.args[0] + additional_info,)
        raise e

    return output_file_path

download_dataset_parquet

download_dataset_parquet(description: dict | OpenMLDataset, download_all_files: bool = False) -> Path | None

Download dataset parquet file.

PARAMETER	DESCRIPTION
description	Either a dataset description as dict or OpenMLDataset. TYPE: dictionary or OpenMLDataset
download_all_files	If True, download all data found in the bucket to which the description's parquet_url points, only download the parquet file otherwise. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Path | None

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

def download_dataset_parquet(
    self,
    description: dict | OpenMLDataset,
    download_all_files: bool = False,  # noqa: FBT002
) -> Path | None:
    """Download dataset parquet file.

    Parameters
    ----------
    description : dictionary or OpenMLDataset
        Either a dataset description as dict or OpenMLDataset.
    download_all_files: bool, optional (default=False)
        If `True`, download all data found in the bucket to which the description's
        ``parquet_url`` points, only download the parquet file otherwise.

    Returns
    -------
    Path | None
    """
    if isinstance(description, dict):
        url = str(description.get("parquet_url"))
    elif isinstance(description, OpenMLDataset):
        url = str(description._parquet_url)
        assert description.dataset_id is not None
    else:
        raise TypeError("`description` should be either OpenMLDataset or Dict.")

    output_file_path = Path(openml.config.get_minio_download_path(url))
    if download_all_files:
        self._minio.download_minio_bucket(source=url)

    if not output_file_path.is_file():
        try:
            output_file_path = self._minio.download_minio_file(source=url)
        except (
            FileNotFoundError,
            urllib3.exceptions.MaxRetryError,
            minio.error.ServerError,
        ) as e:
            logger.warning(f"Could not download file from {url}: {e}")
            return None
    return output_file_path

download_features_file

download_features_file(dataset_id: int) -> Path

Download features file.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int

RETURNS	DESCRIPTION
Path

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

def download_features_file(self, dataset_id: int) -> Path:
    """Download features file.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.

    Returns
    -------
    Path
    """
    path = f"datasets/features/{dataset_id}"
    file = self._download_file(path)
    self.parse_features_file(file)
    return file

download_qualities_file

download_qualities_file(dataset_id: int) -> Path | None

Download qualities file.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int

RETURNS	DESCRIPTION
Path

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

def download_qualities_file(self, dataset_id: int) -> Path | None:
    """Download qualities file.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.

    Returns
    -------
    Path
    """
    path = f"datasets/qualities/{dataset_id}"
    try:
        file = self._download_file(path)
    except OpenMLServerException as e:
        if e.code == 362 and str(e) == "No qualities found - None":
            # quality file stays as None
            logger.warning(f"No qualities found for dataset {dataset_id}")
            return None
        raise e

    if not self.parse_qualities_file(file):
        logger.warning(f"No qualities found for dataset {dataset_id}")
        return None
    return file

get

get(dataset_id: int, *, download_data: bool = False, cache_format: Literal['pickle', 'feather'] = 'pickle', download_qualities: bool = False, download_features_meta_data: bool = False, download_all_files: bool = False, force_refresh_cache: bool = False) -> OpenMLDataset

Download the OpenML dataset representation, optionally also download actual data file.

PARAMETER	DESCRIPTION
dataset_id	Dataset ID (integer) or dataset name (string) of the dataset to download. TYPE: int or str
download_data	If True, download the data file. TYPE: bool(default=False) DEFAULT: False
cache_format	Format for caching the dataset - may be feather or pickle Note that the default 'pickle' option may load slower than feather when no.of.rows is very high. TYPE: str(default='pickle') in {'pickle', 'feather'} DEFAULT: 'pickle'
download_qualities	Option to download 'qualities' meta-data with the minimal dataset description. TYPE: bool(default=False) DEFAULT: False
download_features_meta_data	Option to download 'features' meta-data with the minimal dataset description. TYPE: bool(default=False) DEFAULT: False
download_all_files	EXPERIMENTAL. Download all files related to the dataset that reside on the server. TYPE: bool DEFAULT: False
force_refresh_cache	Force the cache to delete the cache directory and re-download the data. TYPE: bool(default=False) DEFAULT: False

RETURNS	DESCRIPTION
dataset	The downloaded dataset. TYPE: :class:`openml.OpenMLDataset`

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

def get(
    self,
    dataset_id: int,
    *,
    download_data: bool = False,
    cache_format: Literal["pickle", "feather"] = "pickle",
    download_qualities: bool = False,
    download_features_meta_data: bool = False,
    download_all_files: bool = False,
    force_refresh_cache: bool = False,
) -> OpenMLDataset:
    """Download the OpenML dataset representation, optionally also download actual data file.

    Parameters
    ----------
    dataset_id : int or str
        Dataset ID (integer) or dataset name (string) of the dataset to download.
    download_data : bool (default=False)
        If True, download the data file.
    cache_format : str (default='pickle') in {'pickle', 'feather'}
        Format for caching the dataset - may be feather or pickle
        Note that the default 'pickle' option may load slower than feather when
        no.of.rows is very high.
    download_qualities : bool (default=False)
        Option to download 'qualities' meta-data with the minimal dataset description.
    download_features_meta_data : bool (default=False)
        Option to download 'features' meta-data with the minimal dataset description.
    download_all_files: bool (default=False)
        EXPERIMENTAL. Download all files related to the dataset that reside on the server.
    force_refresh_cache : bool (default=False)
        Force the cache to delete the cache directory and re-download the data.

    Returns
    -------
    dataset : :class:`openml.OpenMLDataset`
        The downloaded dataset.
    """
    path = f"datasets/{dataset_id}"
    try:
        response = self._http.get(path, enable_cache=True, refresh_cache=force_refresh_cache)
        json_content = response.json()
        features_file = None
        qualities_file = None

        if download_features_meta_data:
            features_file = self.download_features_file(dataset_id)
        if download_qualities:
            qualities_file = self.download_qualities_file(dataset_id)

        parquet_file = None
        skip_parquet = (
            os.environ.get(openml.config.OPENML_SKIP_PARQUET_ENV_VAR, "false").casefold()
            == "true"
        )
        download_parquet = "parquet_url" in json_content and not skip_parquet
        if download_parquet and (download_data or download_all_files):
            try:
                parquet_file = self.download_dataset_parquet(
                    json_content,
                    download_all_files=download_all_files,
                )
            except urllib3.exceptions.MaxRetryError:
                parquet_file = None

        arff_file = None
        if parquet_file is None and download_data:
            if download_parquet:
                logger.warning("Failed to download parquet, fallback on ARFF.")
            arff_file = self.download_dataset_arff(json_content)
    except OpenMLServerException as e:
        # if there was an exception
        # check if the user had access to the dataset
        if e.code == NO_ACCESS_GRANTED_ERRCODE:
            raise OpenMLPrivateDatasetError(e.message) from None

        raise e

    return self._create_dataset_from_json(
        json_content,
        features_file=features_file,
        qualities_file=qualities_file,
        arff_file=arff_file,
        parquet_file=parquet_file,
        cache_format=cache_format,
    )

get_features

get_features(dataset_id: int, force_refresh_cache: bool = False) -> dict[int, OpenMLDataFeature]

Get features of a dataset from server.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int
force_refresh_cache	Refresh the cache and re-download the features file. TYPE: bool(default=False) DEFAULT: False

RETURNS	DESCRIPTION
dict[int, OpenMLDataFeature]
Dictionary mapping feature index to OpenMLDataFeature.

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

def get_features(
    self,
    dataset_id: int,
    force_refresh_cache: bool = False,  # noqa: FBT002
) -> dict[int, OpenMLDataFeature]:
    """Get features of a dataset from server.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.
    force_refresh_cache : bool (default=False)
        Refresh the cache and re-download the features file.

    Returns
    -------
    dict[int, OpenMLDataFeature]
    Dictionary mapping feature index to OpenMLDataFeature.
    """
    path = f"datasets/features/{dataset_id}"
    json = self._http.get(path, enable_cache=True, refresh_cache=force_refresh_cache).json()

    return self._parse_features_json(json)

get_online_dataset_format

get_online_dataset_format(dataset_id: int) -> str

Get the dataset format for a given dataset id from the OpenML website.

PARAMETER	DESCRIPTION
dataset_id	A dataset id. TYPE: int

RETURNS	DESCRIPTION
str	Dataset format.

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

def get_online_dataset_format(self, dataset_id: int) -> str:
    """Get the dataset format for a given dataset id from the OpenML website.

    Parameters
    ----------
    dataset_id : int
        A dataset id.

    Returns
    -------
    str
        Dataset format.
    """
    dataset_json = self._http.get(f"datasets/{dataset_id}").json()
    # build a dict from the json and get the format from the dataset description
    return dataset_json["format"].lower()  # type: ignore

get_qualities

get_qualities(dataset_id: int, force_refresh_cache: bool = False) -> dict[str, float] | None

Get qualities of a dataset from server.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int
force_refresh_cache	Refresh the cache and re-download the qualities file. TYPE: bool(default=False) DEFAULT: False

RETURNS	DESCRIPTION
dict[str, float] | None
Dictionary mapping quality name to quality value.

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

def get_qualities(
    self,
    dataset_id: int,
    force_refresh_cache: bool = False,  # noqa: FBT002
) -> dict[str, float] | None:
    """Get qualities of a dataset from server.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.
    force_refresh_cache : bool (default=False)
        Refresh the cache and re-download the qualities file.

    Returns
    -------
    dict[str, float] | None
    Dictionary mapping quality name to quality value.
    """
    path = f"datasets/qualities/{dataset_id!s}"
    try:
        qualities_json = self._http.get(
            path, enable_cache=True, refresh_cache=force_refresh_cache
        ).json()
    except OpenMLServerException as e:
        if e.code == 362 and str(e) == "No qualities found - None":
            logger.warning(f"No qualities found for dataset {dataset_id}")
            return None

        raise e

    qualities = self._parse_qualities_json(qualities_json)
    if not qualities:
        logger.warning(f"No qualities found for dataset {dataset_id}")
        return None
    return qualities

list

list(limit: int, offset: int, *, data_id: list[int] | None = None, **kwargs: Any) -> DataFrame

Perform api call to return a list of all datasets.

PARAMETER	DESCRIPTION
The
ones
display_errors
default
limit	The maximum number of datasets to show. TYPE: int
offset	The number of datasets to skip, starting from the first. TYPE: int
data_id	TYPE: list[int] | None DEFAULT: None
kwargs	Legal filter operators (keys in the dict): tag, status, limit, offset, data_name, data_version, number_instances, number_features, number_classes, number_missing_values. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
datasets	TYPE: dataframe

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

def list(
    self,
    limit: int,
    offset: int,
    *,
    data_id: builtins.list[int] | None = None,
    **kwargs: Any,
) -> pd.DataFrame:
    """
    Perform api call to return a list of all datasets.

    Parameters
    ----------
    The arguments that are lists are separated from the single value
    ones which are put into the kwargs.
    display_errors is also separated from the kwargs since it has a
    default value.

    limit : int
        The maximum number of datasets to show.
    offset : int
        The number of datasets to skip, starting from the first.
    data_id: list[int], optional

    kwargs : dict, optional
        Legal filter operators (keys in the dict):
        tag, status, limit, offset, data_name, data_version, number_instances,
        number_features, number_classes, number_missing_values.

    Returns
    -------
    datasets : dataframe
    """
    json: dict[str, Any] = {"pagination": {}}

    if limit is not None:
        json["pagination"]["limit"] = limit
    if offset is not None:
        json["pagination"]["offset"] = offset
    if data_id is not None:
        json["data_id"] = data_id
    if kwargs is not None:
        for operator, value in kwargs.items():
            if value is not None:
                json[operator] = value

    api_call = "datasets/list"
    datasets_list = self._http.post(path=api_call, json=json, use_api_key=False).json()
    # Minimalistic check if the JSON is useful
    assert isinstance(datasets_list, list), type(datasets_list)

    return self._parse_list_json(datasets_list)

list_qualities

list_qualities() -> list[str]

Return list of data qualities available.

The function performs an API call to retrieve the entire list of data qualities that are computed on the datasets uploaded.

RETURNS	DESCRIPTION
list

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

def list_qualities(self) -> builtins.list[str]:
    """Return list of data qualities available.

    The function performs an API call to retrieve the entire list of
    data qualities that are computed on the datasets uploaded.

    Returns
    -------
    list
    """
    api_call = "datasets/qualities/list"
    qualities = self._http.get(api_call).json()
    # Minimalistic check if the JSON is useful
    if "data_qualities_list" not in qualities:
        raise ValueError('Error in return JSON, does not contain "data_qualities_list"')

    if not isinstance(qualities["data_qualities_list"]["quality"], list):
        raise TypeError('Error in return JSON, does not contain "quality" as a list')

    return qualities["data_qualities_list"]["quality"]

parse_features_file

parse_features_file(features_file: Path, features_pickle_file: Path | None = None) -> dict[int, OpenMLDataFeature]

Parse features file (json) and store it as a pickle file.

PARAMETER	DESCRIPTION
features_file	Path to features file. TYPE: Path
features_pickle_file	Path to pickle file for features. TYPE: Path DEFAULT: None

RETURNS	DESCRIPTION
dict[int, OpenMLDataFeature]

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

def parse_features_file(
    self, features_file: Path, features_pickle_file: Path | None = None
) -> dict[int, OpenMLDataFeature]:
    """
    Parse features file (json) and store it as a pickle file.

    Parameters
    ----------
    features_file : Path
        Path to features file.
    features_pickle_file : Path, optional
        Path to pickle file for features.

    Returns
    -------
    dict[int, OpenMLDataFeature]
    """
    if features_pickle_file is None:
        features_pickle_file = features_file.with_suffix(features_file.suffix + ".pkl")
    if features_file.suffix == ".xml":
        # can fallback to v1 if the file is .xml
        raise NotImplementedError("Unable to Parse .xml from v1")

    with Path(features_file).open("r", encoding="utf8") as fh:
        features_json = json.load(fh)

    features = self._parse_features_json(features_json)

    with features_pickle_file.open("wb") as fh_binary:
        pickle.dump(features, fh_binary)

    return features

parse_qualities_file

parse_qualities_file(qualities_file: Path, qualities_pickle_file: Path | None = None) -> dict[str, float]

Parse qualities file (json) and store it as a pickle file.

PARAMETER	DESCRIPTION
qualities_file	Path to qualities file. TYPE: Path
qualities_pickle_file	Path to pickle file for qualities. TYPE: Path DEFAULT: None

RETURNS	DESCRIPTION
qualities	TYPE: dict[str, float]

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

def parse_qualities_file(
    self, qualities_file: Path, qualities_pickle_file: Path | None = None
) -> dict[str, float]:
    """Parse qualities file (json) and store it as a pickle file.

    Parameters
    ----------
    qualities_file : Path
        Path to qualities file.
    qualities_pickle_file : Path, optional
        Path to pickle file for qualities.

    Returns
    -------
    qualities : dict[str, float]
    """
    if qualities_pickle_file is None:
        qualities_pickle_file = qualities_file.with_suffix(qualities_file.suffix + ".pkl")
    if qualities_file.suffix == ".xml":
        # can fallback to v1 if the file is .xml
        raise NotImplementedError("Unable to Parse .xml from v1")

    with Path(qualities_file).open("r", encoding="utf8") as fh:
        qualities_json = json.load(fh)

    qualities = self._parse_qualities_json(qualities_json)

    with qualities_pickle_file.open("wb") as fh_binary:
        pickle.dump(qualities, fh_binary)

    return qualities

status_update

status_update(dataset_id: int, status: Literal['active', 'deactivated']) -> None

Updates the status of a dataset to either 'active' or 'deactivated'. Please see the OpenML API documentation for a description of the status and all legal status transitions: docs.openml.org/concepts/data/#dataset-status

PARAMETER	DESCRIPTION
dataset_id	The data id of the dataset TYPE: int
status	'active' or 'deactivated' TYPE: (str,)

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

def status_update(self, dataset_id: int, status: Literal["active", "deactivated"]) -> None:
    """
    Updates the status of a dataset to either 'active' or 'deactivated'.
    Please see the OpenML API documentation for a description of the status
    and all legal status transitions:
    https://docs.openml.org/concepts/data/#dataset-status

    Parameters
    ----------
    dataset_id : int
        The data id of the dataset
    status : str,
        'active' or 'deactivated'
    """
    legal_status = {"active", "deactivated"}
    if status not in legal_status:
        raise ValueError(f"Illegal status value. Legal values: {legal_status}")

    data: dict[str, str | int] = {"dataset_id": dataset_id, "status": status}
    result = self._http.post(
        f"datasets/status/update/?api_key={self._http.api_key}", json=data, use_api_key=False
    ).json()
    server_data_id = result["dataset_id"]
    server_status = result["status"]
    if status != server_status or int(dataset_id) != int(server_data_id):
        # This should never happen
        raise ValueError("Data id/status does not match")

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)
        try:
            parsed_response = xmltodict.parse(response.content)
        except xml.parsers.expat.ExpatError as e:
            msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
            raise OpenMLServerError(msg) from e
        return f"oml:{endpoint_name}_delete" in parsed_response
    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)
    try:
        parsed_response = xmltodict.parse(response.content)
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)
        try:
            parsed_response = xmltodict.parse(response.content)
        except xml.parsers.expat.ExpatError as e:
            msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
            raise OpenMLServerError(msg) from e
        return f"oml:{endpoint_name}_delete" in parsed_response
    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)
    try:
        parsed_response = xmltodict.parse(response.content)
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)
        try:
            parsed_response = xmltodict.parse(response.content)
        except xml.parsers.expat.ExpatError as e:
            msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
            raise OpenMLServerError(msg) from e
        return f"oml:{endpoint_name}_delete" in parsed_response
    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)
    try:
        parsed_response = xmltodict.parse(response.content)
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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

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)
        try:
            parsed_response = xmltodict.parse(response.content)
        except xml.parsers.expat.ExpatError as e:
            msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
            raise OpenMLServerError(msg) from e
        return f"oml:{endpoint_name}_delete" in parsed_response
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

exists

exists(name: str, external_version: str) -> int | bool

Check if a flow exists on the OpenML server.

PARAMETER	DESCRIPTION
name	The name of the flow. TYPE: str
external_version	The external version of the flow. TYPE: str

RETURNS	DESCRIPTION
int | bool	The flow ID if the flow exists, False otherwise.

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

def exists(self, name: str, external_version: str) -> int | bool:
    """Check if a flow exists on the OpenML server.

    Parameters
    ----------
    name : str
        The name of the flow.
    external_version : str
        The external version of the flow.

    Returns
    -------
    int | bool
        The flow ID if the flow exists, False otherwise.
    """
    if not (isinstance(name, str) and len(name) > 0):
        raise ValueError("Argument 'name' should be a non-empty string")
    if not (isinstance(external_version, str) and len(external_version) > 0):
        raise ValueError("Argument 'version' should be a non-empty string")

    data: dict[str, str] = {"name": name, "external_version": external_version}
    if self._http.api_key:
        data["api_key"] = self._http.api_key

    xml_response = self._http.post("flow/exists", data=data, use_api_key=False).text
    result_dict = xmltodict.parse(xml_response)
    # Detect error payloads and raise
    if "oml:error" in result_dict:
        err = result_dict["oml:error"]
        code = int(err.get("oml:code", 0)) if "oml:code" in err else None
        message = err.get("oml:message", "Server returned an error")
        raise OpenMLServerException(message=message, code=code)

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

get

get(flow_id: int, *, reset_cache: bool = False) -> OpenMLFlow

Get a flow from the OpenML server.

PARAMETER	DESCRIPTION
flow_id	The ID of the flow to retrieve. TYPE: int
reset_cache	Whether to reset the cache for this request. TYPE: (bool, optional(default=False)) DEFAULT: False

RETURNS	DESCRIPTION
OpenMLFlow	The retrieved flow object.

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

def get(
    self,
    flow_id: int,
    *,
    reset_cache: bool = False,
) -> OpenMLFlow:
    """Get a flow from the OpenML server.

    Parameters
    ----------
    flow_id : int
        The ID of the flow to retrieve.
    reset_cache : bool, optional (default=False)
        Whether to reset the cache for this request.

    Returns
    -------
    OpenMLFlow
        The retrieved flow object.
    """
    response = self._http.get(
        f"flow/{flow_id}",
        enable_cache=True,
        refresh_cache=reset_cache,
    )
    flow_xml = response.text
    return OpenMLFlow._from_dict(xmltodict.parse(flow_xml))

list

list(limit: int | None = None, offset: int | None = None, tag: str | None = None, uploader: str | None = None) -> DataFrame

List flows on the OpenML server.

PARAMETER	DESCRIPTION
limit	The maximum number of flows to return. By default, all flows are returned. TYPE: int DEFAULT: None
offset	The number of flows to skip before starting to collect the result set. By default, no flows are skipped. TYPE: int DEFAULT: None
tag	The tag to filter flows by. By default, no tag filtering is applied. TYPE: str DEFAULT: None
uploader	The user to filter flows by. By default, no user filtering is applied. TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
DataFrame	A DataFrame containing the list of flows.

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

def list(
    self,
    limit: int | None = None,
    offset: int | None = None,
    tag: str | None = None,
    uploader: str | None = None,
) -> pd.DataFrame:
    """List flows on the OpenML server.

    Parameters
    ----------
    limit : int, optional
        The maximum number of flows to return.
        By default, all flows are returned.
    offset : int, optional
        The number of flows to skip before starting to collect the result set.
        By default, no flows are skipped.
    tag : str, optional
        The tag to filter flows by.
        By default, no tag filtering is applied.
    uploader : str, optional
        The user to filter flows by.
        By default, no user filtering is applied.

    Returns
    -------
    pd.DataFrame
        A DataFrame containing the list of flows.
    """
    api_call = "flow/list"
    if limit is not None:
        api_call += f"/limit/{limit}"
    if offset is not None:
        api_call += f"/offset/{offset}"
    if tag is not None:
        api_call += f"/tag/{quote(str(tag), safe='')}"
    if uploader is not None:
        api_call += f"/uploader/{quote(str(uploader), safe='')}"

    response = self._http.get(api_call)
    xml_string = response.text
    flows_dict = xmltodict.parse(xml_string, force_list=("oml:flow",))

    if "oml:error" in flows_dict:
        err = flows_dict["oml:error"]
        code = int(err.get("oml:code", 0)) if "oml:code" in err else None
        message = err.get("oml:message", "Server returned an error")
        raise OpenMLServerException(message=message, code=code)

    assert isinstance(flows_dict["oml:flows"]["oml:flow"], list), type(flows_dict["oml:flows"])
    assert flows_dict["oml:flows"]["@xmlns:oml"] == "http://openml.org/openml", flows_dict[
        "oml:flows"
    ]["@xmlns:oml"]

    flows: dict[int, dict[str, Any]] = {}
    for flow_ in flows_dict["oml:flows"]["oml:flow"]:
        fid = int(flow_["oml:id"])
        flow_row = {
            "id": fid,
            "full_name": flow_["oml:full_name"],
            "name": flow_["oml:name"],
            "version": flow_["oml:version"],
            "external_version": flow_["oml:external_version"],
            "uploader": flow_["oml:uploader"],
        }
        flows[fid] = flow_row

    return pd.DataFrame.from_dict(flows, orient="index")

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)
    try:
        parsed_response = xmltodict.parse(response.content)
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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

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

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

exists

exists(name: str, external_version: str) -> int | bool

Check if a flow exists on the OpenML v2 server.

PARAMETER	DESCRIPTION
name	The name of the flow. TYPE: str
external_version	The external version of the flow. TYPE: str

RETURNS	DESCRIPTION
int | bool	The flow ID if the flow exists, False otherwise.

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

def exists(self, name: str, external_version: str) -> int | bool:
    """Check if a flow exists on the OpenML v2 server.

    Parameters
    ----------
    name : str
        The name of the flow.
    external_version : str
        The external version of the flow.

    Returns
    -------
    int | bool
        The flow ID if the flow exists, False otherwise.
    """
    if not (isinstance(name, str) and len(name) > 0):
        raise ValueError("Argument 'name' should be a non-empty string")
    if not (isinstance(external_version, str) and len(external_version) > 0):
        raise ValueError("Argument 'version' should be a non-empty string")

    name_path = quote(name, safe="")
    version_path = quote(external_version, safe="")

    try:
        response = self._http.get(f"flows/exists/{name_path}/{version_path}/")
        result = response.json()
        flow_id: int | bool = result.get("flow_id", False)
        return flow_id
    except OpenMLServerNoResult:
        return False
    except OpenMLServerException as err:
        if err.code == 404:
            return False
        raise

get

get(flow_id: int, *, reset_cache: bool = False) -> OpenMLFlow

Get a flow from the OpenML v2 server.

PARAMETER	DESCRIPTION
flow_id	The ID of the flow to retrieve. TYPE: int
reset_cache	Whether to reset the cache for this request. TYPE: (bool, optional(default=False)) DEFAULT: False

RETURNS	DESCRIPTION
OpenMLFlow	The retrieved flow object.

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

def get(
    self,
    flow_id: int,
    *,
    reset_cache: bool = False,
) -> OpenMLFlow:
    """Get a flow from the OpenML v2 server.

    Parameters
    ----------
    flow_id : int
        The ID of the flow to retrieve.
    reset_cache : bool, optional (default=False)
        Whether to reset the cache for this request.

    Returns
    -------
    OpenMLFlow
        The retrieved flow object.
    """
    response = self._http.get(
        f"flows/{flow_id}/",
        enable_cache=True,
        refresh_cache=reset_cache,
    )
    flow_json = response.json()

    # Convert v2 JSON to v1-compatible dict for OpenMLFlow._from_dict()
    flow_dict = self._convert_v2_to_v1_format(flow_json)
    return OpenMLFlow._from_dict(flow_dict)

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)
        try:
            parsed_response = xmltodict.parse(response.content)
        except xml.parsers.expat.ExpatError as e:
            msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
            raise OpenMLServerError(msg) from e
        return f"oml:{endpoint_name}_delete" in parsed_response
    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)
    try:
        parsed_response = xmltodict.parse(response.content)
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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

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)
        try:
            parsed_response = xmltodict.parse(response.content)
        except xml.parsers.expat.ExpatError as e:
            msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
            raise OpenMLServerError(msg) from e
        return f"oml:{endpoint_name}_delete" in parsed_response
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

get

get(run_id: int, *, reset_cache: bool = False) -> OpenMLRun

Fetch a single run from the OpenML server.

PARAMETER	DESCRIPTION
run_id	The ID of the run to fetch. TYPE: int
reset_cache	Whether to reset the cache. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
OpenMLRun	The run object with all details populated.

RAISES	DESCRIPTION
OpenMLServerException	If the run does not exist or server error occurs.

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

def get(
    self,
    run_id: int,
    *,
    reset_cache: bool = False,
) -> OpenMLRun:  # type: ignore[override]
    """Fetch a single run from the OpenML server.

    Parameters
    ----------
    run_id : int
        The ID of the run to fetch.
    reset_cache : bool, default=False
        Whether to reset the cache.

    Returns
    -------
    OpenMLRun
        The run object with all details populated.

    Raises
    ------
    openml.exceptions.OpenMLServerException
        If the run does not exist or server error occurs.
    """
    path = f"run/{run_id}"
    response = self._http.get(
        path,
        enable_cache=True,
        refresh_cache=reset_cache,
    )
    xml_content = response.text
    return openml.runs.functions._create_run_from_xml(xml_content)

list

list(limit: int, offset: int, *, ids: list[int] | None = None, task: list[int] | None = None, setup: list[int] | None = None, flow: list[int] | None = None, uploader: list[int] | None = None, study: int | None = None, tag: str | None = None, display_errors: bool = False, task_type: TaskType | int | None = None) -> DataFrame

List runs from the OpenML server with optional filtering.

PARAMETER	DESCRIPTION
limit	Maximum number of runs to return. TYPE: int
offset	Starting position for pagination. TYPE: int
ids	List of run IDs to filter by. TYPE: list of int DEFAULT: None
task	List of task IDs to filter by. TYPE: list of int DEFAULT: None
setup	List of setup IDs to filter by. TYPE: list of int DEFAULT: None
flow	List of flow IDs to filter by. TYPE: list of int DEFAULT: None
uploader	List of uploader user IDs to filter by. TYPE: list of int DEFAULT: None
study	Study ID to filter by. TYPE: int DEFAULT: None
tag	Tag to filter by. TYPE: str DEFAULT: None
display_errors	If True, include runs with error messages. TYPE: bool DEFAULT: False
task_type	Task type ID to filter by. TYPE: TaskType or int DEFAULT: None

RETURNS	DESCRIPTION
DataFrame	DataFrame with columns: run_id, task_id, setup_id, flow_id, uploader, task_type, upload_time, error_message.

RAISES	DESCRIPTION
ValueError	If the server response is invalid or malformed.

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

def list(  # type: ignore[valid-type]  # noqa: PLR0913
    self,
    limit: int,
    offset: int,
    *,
    ids: builtins.list[int] | None = None,
    task: builtins.list[int] | None = None,
    setup: builtins.list[int] | None = None,
    flow: builtins.list[int] | None = None,
    uploader: builtins.list[int] | None = None,
    study: int | None = None,
    tag: str | None = None,
    display_errors: bool = False,
    task_type: TaskType | int | None = None,
) -> pd.DataFrame:
    """List runs from the OpenML server with optional filtering.

    Parameters
    ----------
    limit : int
        Maximum number of runs to return.
    offset : int
        Starting position for pagination.
    ids : list of int, optional
        List of run IDs to filter by.
    task : list of int, optional
        List of task IDs to filter by.
    setup : list of int, optional
        List of setup IDs to filter by.
    flow : list of int, optional
        List of flow IDs to filter by.
    uploader : list of int, optional
        List of uploader user IDs to filter by.
    study : int, optional
        Study ID to filter by.
    tag : str, optional
        Tag to filter by.
    display_errors : bool, default=False
        If True, include runs with error messages.
    task_type : TaskType or int, optional
        Task type ID to filter by.

    Returns
    -------
    pd.DataFrame
        DataFrame with columns: run_id, task_id, setup_id, flow_id,
        uploader, task_type, upload_time, error_message.

    Raises
    ------
    ValueError
        If the server response is invalid or malformed.
    """
    path = self._build_url(
        limit=limit,
        offset=offset,
        ids=ids,
        task=task,
        setup=setup,
        flow=flow,
        uploader=uploader,
        study=study,
        tag=tag,
        display_errors=display_errors,
        task_type=task_type,
    )
    xml_string = self._http.get(path).text
    return self._parse_list_xml(xml_string)

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)
    try:
        parsed_response = xmltodict.parse(response.content)
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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

V2 API resource for runs. Currently read-only until V2 server supports POST.

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

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

get

get(run_id: int, *, reset_cache: bool = False) -> OpenMLRun

Fetch a single run from the V2 server.

PARAMETER	DESCRIPTION
run_id	The ID of the run to fetch. TYPE: int
reset_cache	Whether to reset the cache. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
OpenMLRun	The run object.

RAISES	DESCRIPTION
OpenMLNotSupportedError	V2 server API not yet available for this operation.

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

def get(
    self,
    run_id: int,  # noqa: ARG002
    *,
    reset_cache: bool = False,  # noqa: ARG002
) -> OpenMLRun:  # type: ignore[override]
    """Fetch a single run from the V2 server.

    Parameters
    ----------
    run_id : int
        The ID of the run to fetch.
    reset_cache : bool, default=False
        Whether to reset the cache.

    Returns
    -------
    OpenMLRun
        The run object.

    Raises
    ------
    OpenMLNotSupportedError
        V2 server API not yet available for this operation.
    """
    self._not_supported(method="get")

list

list(limit: int, offset: int, *, ids: list[int] | None = None, task: list[int] | None = None, setup: list[int] | None = None, flow: list[int] | None = None, uploader: list[int] | None = None, study: int | None = None, tag: str | None = None, display_errors: bool = False, task_type: TaskType | int | None = None) -> DataFrame

List runs from the V2 server.

RAISES	DESCRIPTION
OpenMLNotSupportedError	V2 server API not yet available for this operation.

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

def list(  # type: ignore[valid-type]  # noqa: PLR0913
    self,
    limit: int,  # noqa: ARG002
    offset: int,  # noqa: ARG002
    *,
    ids: builtins.list[int] | None = None,  # noqa: ARG002
    task: builtins.list[int] | None = None,  # noqa: ARG002
    setup: builtins.list[int] | None = None,  # noqa: ARG002
    flow: builtins.list[int] | None = None,  # noqa: ARG002
    uploader: builtins.list[int] | None = None,  # noqa: ARG002
    study: int | None = None,  # noqa: ARG002
    tag: str | None = None,  # noqa: ARG002
    display_errors: bool = False,  # noqa: ARG002
    task_type: TaskType | int | None = None,  # noqa: ARG002
) -> pd.DataFrame:
    """List runs from the V2 server.

    Raises
    ------
    OpenMLNotSupportedError
        V2 server API not yet available for this operation.
    """
    self._not_supported(method="list")

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)
        try:
            parsed_response = xmltodict.parse(response.content)
        except xml.parsers.expat.ExpatError as e:
            msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
            raise OpenMLServerError(msg) from e
        return f"oml:{endpoint_name}_delete" in parsed_response
    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)
    try:
        parsed_response = xmltodict.parse(response.content)
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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

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)
        try:
            parsed_response = xmltodict.parse(response.content)
        except xml.parsers.expat.ExpatError as e:
            msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
            raise OpenMLServerError(msg) from e
        return f"oml:{endpoint_name}_delete" in parsed_response
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

list

list(limit: int | None = None, offset: int | None = None, status: str | None = None, main_entity_type: str | None = None, uploader: list[int] | None = None, benchmark_suite: int | None = None) -> DataFrame

List studies using V1 API.

PARAMETER	DESCRIPTION
limit	Maximum number of studies to return. TYPE: int DEFAULT: None
offset	Number of studies to skip. TYPE: int DEFAULT: None
status	Filter by status (active, in_preparation, deactivated, all). TYPE: str DEFAULT: None
main_entity_type	Filter by main entity type (run, task). TYPE: str DEFAULT: None
uploader	Filter by uploader IDs. TYPE: list[int] DEFAULT: None
benchmark_suite	Filter by benchmark suite ID. TYPE: int DEFAULT: None

RETURNS	DESCRIPTION
DataFrame	DataFrame containing study information.

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

def list(  # noqa: PLR0913,PLR0917
    self,
    limit: int | None = None,
    offset: int | None = None,
    status: str | None = None,
    main_entity_type: str | None = None,
    uploader: builtins.list[int] | None = None,
    benchmark_suite: int | None = None,
) -> pd.DataFrame:
    """List studies using V1 API.

    Parameters
    ----------
    limit : int, optional
        Maximum number of studies to return.
    offset : int, optional
        Number of studies to skip.
    status : str, optional
        Filter by status (active, in_preparation, deactivated, all).
    main_entity_type : str, optional
        Filter by main entity type (run, task).
    uploader : list[int], optional
        Filter by uploader IDs.
    benchmark_suite : int, optional
        Filter by benchmark suite ID.

    Returns
    -------
    pd.DataFrame
        DataFrame containing study information.
    """
    api_call = self._build_url(
        limit=limit,
        offset=offset,
        status=status,
        main_entity_type=main_entity_type,
        uploader=uploader,
        benchmark_suite=benchmark_suite,
    )
    response = self._http.get(api_call)
    xml_string = response.content.decode("utf-8")
    return self._parse_list_xml(xml_string)

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)
    try:
        parsed_response = xmltodict.parse(response.content)
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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

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 | None = None, offset: int | None = None, status: str | None = None, main_entity_type: str | None = None, uploader: list[int] | None = None, benchmark_suite: int | None = None) -> DataFrame

V2 API for listing studies is not yet available.

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

def list(  # noqa: PLR0913,PLR0917
    self,
    limit: int | None = None,  # noqa: ARG002
    offset: int | None = None,  # noqa: ARG002
    status: str | None = None,  # noqa: ARG002
    main_entity_type: str | None = None,  # noqa: ARG002
    uploader: builtins.list[int] | None = None,  # noqa: ARG002
    benchmark_suite: int | None = None,  # noqa: ARG002
) -> pd.DataFrame:
    """V2 API for listing studies is not yet available."""
    self._not_supported(method="list")

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

download_split abstractmethod

download_split(url: str, *, refresh_cache: bool = False) -> Path

Download a task's split file and return its path in the cache.

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

@abstractmethod
def download_split(self, url: str, *, refresh_cache: bool = False) -> Path:
    """Download a task's split file and return its path in the cache."""
    ...

get abstractmethod

get(task_id: int) -> OpenMLTask

API v1: GET /task/{task_id}

API v2: GET /tasks/{task_id}

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

@abstractmethod
def get(
    self,
    task_id: int,
) -> OpenMLTask:
    """
    API v1:
        GET /task/{task_id}

    API v2:
        GET /tasks/{task_id}
    """
    ...

list abstractmethod

list(limit: int, offset: int, task_type: TaskType | int | None = None, *, estimation_procedures: list[dict[str, Any]], **kwargs: Any) -> DataFrame

List tasks with filters.

API v1: GET /task/list

API v2: Not available.

RETURNS	DESCRIPTION
DataFrame

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

@abstractmethod
def list(
    self,
    limit: int,
    offset: int,
    task_type: TaskType | int | None = None,
    *,
    estimation_procedures: builtins.list[dict[str, Any]],
    **kwargs: Any,
) -> pd.DataFrame:
    """
    List tasks with filters.

    API v1:
        GET /task/list

    API v2:
        Not available.

    Returns
    -------
    pandas.DataFrame
    """
    ...

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

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)
        try:
            parsed_response = xmltodict.parse(response.content)
        except xml.parsers.expat.ExpatError as e:
            msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
            raise OpenMLServerError(msg) from e
        return f"oml:{endpoint_name}_delete" in parsed_response
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

download_split

download_split(url: str, *, refresh_cache: bool = False) -> Path

Download a task's split file and return its path in the cache.

PARAMETER	DESCRIPTION
url	URL of the split file. TYPE: str
refresh_cache	Whether to replace the file if it is already cached. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Path

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

def download_split(self, url: str, *, refresh_cache: bool = False) -> Path:
    """Download a task's split file and return its path in the cache.

    Parameters
    ----------
    url : str
        URL of the split file.
    refresh_cache : bool, optional
        Whether to replace the file if it is already cached.

    Returns
    -------
    Path
    """
    self._http.get(url, enable_cache=True, refresh_cache=refresh_cache)
    return self._http.cache_path_from_url(url)

get

get(task_id: int) -> OpenMLTask

Download OpenML task for a given task ID.

Downloads the task representation.

PARAMETER	DESCRIPTION
task_id	The OpenML task id of the task to download. TYPE: int

RETURNS	DESCRIPTION
task	TYPE: OpenMLTask

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

def get(self, task_id: int) -> OpenMLTask:
    """Download OpenML task for a given task ID.

    Downloads the task representation.

    Parameters
    ----------
    task_id : int
        The OpenML task id of the task to download.

    Returns
    -------
    task: OpenMLTask
    """
    response = self._http.get(f"task/{task_id}", enable_cache=True)
    return self._create_task_from_xml(response.text)

list

list(limit: int, offset: int, task_type: TaskType | int | None = None, *, estimation_procedures: list[dict[str, Any]], **kwargs: Any) -> DataFrame

Perform the api call to return a number of tasks having the given filters.

PARAMETER	DESCRIPTION
Filter
it
type
limit	TYPE: int
offset	TYPE: int
task_type	Refers to the type of task. TYPE: TaskType DEFAULT: None
estimation_procedures	All estimation procedures on OpenML, used to resolve the procedure ids returned by the listing into names. TYPE: list of dict
kwargs	Legal filter operators: tag, task_id (list), data_tag, status, limit, offset, data_id, data_name, number_instances, number_features, number_classes, number_missing_values. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
dataframe

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

def list(
    self,
    limit: int,
    offset: int,
    task_type: TaskType | int | None = None,
    *,
    estimation_procedures: builtins.list[dict[str, Any]],
    **kwargs: Any,
) -> pd.DataFrame:
    """
    Perform the api call to return a number of tasks having the given filters.

    Parameters
    ----------
    Filter task_type is separated from the other filters because
    it is used as task_type in the task description, but it is named
    type when used as a filter in list tasks call.
    limit: int
    offset: int
    task_type : TaskType, optional
        Refers to the type of task.
    estimation_procedures : list of dict
        All estimation procedures on OpenML, used to resolve the procedure
        ids returned by the listing into names.
    kwargs: dict, optional
        Legal filter operators: tag, task_id (list), data_tag, status, limit,
        offset, data_id, data_name, number_instances, number_features,
        number_classes, number_missing_values.

    Returns
    -------
    dataframe
    """
    api_call = self._build_url(limit, offset, task_type, kwargs)
    return self._parse_list_xml(api_call, estimation_procedures)

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)
    try:
        parsed_response = xmltodict.parse(response.content)
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    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

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

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

download_split

download_split(url: str, *, refresh_cache: bool = False) -> Path

Download a task's split file and return its path in the cache.

PARAMETER	DESCRIPTION
url	URL of the split file. TYPE: str
refresh_cache	Whether to replace the file if it is already cached. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Path

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

def download_split(self, url: str, *, refresh_cache: bool = False) -> Path:
    """Download a task's split file and return its path in the cache.

    Parameters
    ----------
    url : str
        URL of the split file.
    refresh_cache : bool, optional
        Whether to replace the file if it is already cached.

    Returns
    -------
    Path
    """
    self._http.get(url, enable_cache=True, refresh_cache=refresh_cache)
    return self._http.cache_path_from_url(url)

get

get(task_id: int) -> OpenMLTask

Download OpenML task for a given task ID.

Downloads the task representation.

PARAMETER	DESCRIPTION
task_id	The OpenML task id of the task to download. TYPE: int

RETURNS	DESCRIPTION
task	TYPE: OpenMLTask

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

def get(self, task_id: int) -> OpenMLTask:
    """Download OpenML task for a given task ID.

    Downloads the task representation.

    Parameters
    ----------
    task_id : int
        The OpenML task id of the task to download.

    Returns
    -------
    task: OpenMLTask
    """
    response = self._http.get(f"tasks/{task_id}", enable_cache=True)
    return self._create_task_from_json(response.json())