setup

openml._api.resources.setup

SetupV1API

SetupV1API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV1API, SetupAPI

V1 XML API implementation for setups.

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

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

delete

delete(resource_id: int) -> bool

Delete a resource using the V1 API.

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

RETURNS	DESCRIPTION
bool	True if the server confirms successful deletion.

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

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

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

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

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

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

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

exists

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

Checks whether a hyperparameter configuration already exists on the server.

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

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

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

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

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

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

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

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

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

get

get(setup_id: int) -> OpenMLSetup

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

PARAMETER	DESCRIPTION
setup_id	The Openml setup_id TYPE: int

RETURNS	DESCRIPTION
OpenMLSetup	An initialized OpenMLSetup object parsed from the XML

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

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

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

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

    return SetupV1API._create_setup(result_dict)

list

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

Perform API call /setup/list/{filters}

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

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

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

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

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

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

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

    return SetupV1API._parse_list_xml(xml_content)

publish

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

Publish a new resource using the V1 API.

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

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

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

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

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

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

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

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

tag

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

Add a tag to a resource using the V1 API.

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

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

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

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

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

    Parameters
    ----------
    resource_id : int
        Identifier of the resource to tag.
    tag : str
        Tag to associate with the resource.

    Returns
    -------
    list of str
        Updated list of tags assigned to the resource.

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

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

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

    return tags

untag

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

Remove a tag from a resource using the V1 API.

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

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

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

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

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

    Parameters
    ----------
    resource_id : int
        Identifier of the resource to untag.
    tag : str
        Tag to remove from the resource.

    Returns
    -------
    list of str
        Updated list of tags assigned to the resource.

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

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

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

    return tags

SetupV2API

SetupV2API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV2API, SetupAPI

V2 JSoN API implementation for setups.

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

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