Skip to content

Manage tasks

Tasks are unversioned and belong to a project. Use these methods to retrieve, import, load, update, or delete tasks.

Read

get_task

Get an unversioned task entity from the backend.

Parameters:

Name Type Description Default
identifier str

Entity ID or entity key in the format store://<project>/<entity_type>/<kind>/<uuid>.

required
project str

Project name. Required when identifier is an entity ID.

None

Returns:

Type Description
Task

Retrieved task entity.

Examples:

Get a task by ID and project:

import digitalhub as dh

task = dh.get_task("my-task-id", project="my-project")

Get a task by key:

task = dh.get_task("store://my-project/task/python+job/my-task-id")
list_tasks

List task entities in a project.

Parameters:

Name Type Description Default
project str

Project name.

required
q str

Query string used to filter entities.

None
name str

Entity name used to filter results.

None
kind str

Entity kind used to filter results.

None
user str

User who created the entity.

None
state str

Entity state used to filter results.

None
created str

Creation date filter.

None
updated str

Update date filter.

None
function str

Function reference used to filter results.

None
workflow str

Workflow reference used to filter results.

None

Returns:

Type Description
list[Task]

Task entities matching the filters.

Examples:

List tasks in a project:

import digitalhub as dh

tasks = dh.list_tasks(project="my-project")
import_task

Import a task entity from a YAML file or entity key.

Parameters:

Name Type Description Default
file str

Path to a YAML file containing the entity descriptor. Provide either file or key.

None
key str

Entity key in the format store://<project>/<entity_type>/<kind>/<uuid>. Provide either file or key.

None
reset_id bool

Whether to generate a new entity identifier instead of preserving the identifier from the imported entity.

False
context str

Project name used for context resolution. If omitted, the project from the entity descriptor is used.

None

Returns:

Type Description
Task

Imported task entity.

Examples:

Import a task from a YAML file:

import digitalhub as dh

task = dh.import_task("my-task.yaml")
load_task

Load a task entity from a YAML file.

Parameters:

Name Type Description Default
file str

Path to a YAML file containing the entity descriptor.

required

Returns:

Type Description
Task

Loaded task entity. An existing entity is updated when it can be identified; otherwise, a new entity is created.

Examples:

Load a task from a YAML file:

import digitalhub as dh

task = dh.load_task("my-task.yaml")

Update

Update a task after changing its mutable metadata. Its specification is immutable where required by the backend.

update_task

Update a task entity in the backend.

Parameters:

Name Type Description Default
entity Task

Entity to update. The entity specification is immutable.

required

Returns:

Type Description
Task

Updated task entity.

Examples:

Update a task description:

import digitalhub as dh

task = dh.get_task("my-task-id", project="my-project")
task.set_description("Updated task")
task = dh.update_task(task)

Delete

Delete a task from the backend.

delete_task

Delete an unversioned task entity from the backend.

Parameters:

Name Type Description Default
identifier str

Entity ID or entity key in the format store://<project>/<entity_type>/<kind>/<uuid>.

required
project str

Project name. Required when identifier is an entity ID.

None
entity_id str

Identifier of the entity to delete. If omitted, identifier is used.

None
cascade bool

Whether to request cascade deletion from the backend.

True

Returns:

Type Description
dict

Response data from the backend.

Examples:

Delete a task by ID and project:

import digitalhub as dh

dh.delete_task("my-task-id", project="my-project")

Delete a task by key:

dh.delete_task("store://my-project/task/python+job/my-task-id")