Skip to content

run

openml._api.resources.run #

RunV1API #

RunV1API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV1API, RunAPI

Source code in openml/_api/resources/base/base.py 
52
53
54
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 
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
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

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 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
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 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
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 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
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 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
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 
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
def untag(self, resource_id: int, tag: str) -> list[str]:
    """
    Remove a tag from a resource using the V1 API.

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

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

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

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

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

    return tags

RunV2API #

RunV2API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV2API, RunAPI

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

Source code in openml/_api/resources/base/base.py 
52
53
54
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 
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
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 
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
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")