Skip to content

Programs

programs

Programs module for interacting with Kaleidoscope programs.

The service allows users to retrieve all available programs in a workspace and filter programs by specific IDs.

Classes:

Name Description
Program

Data model for a Kaleidoscope program.
ProgramsService

Service for managing program retrieval operations.
Example 
# get all programs in the workspace
programs = client.programs.get_programs()

# get several programs by their ids
filtered = client.programs.get_program_by_ids(['prog1_uuid', 'prog2_uuid'])

Program

Bases: _KaleidoscopeBaseModel

Represents a program in the Kaleidoscope system.

A Program is a base model that contains identifying information about a program, including its title and ID.

Attributes:

Name Type Description
title str

The title/name of the program.

ProgramsService 

ProgramsService(client: KaleidoscopeClient)

Service class for managing and retrieving programs (experiments) from Kaleidoscope.

This service provides methods to interact with the programs API endpoint, allowing users to fetch all available programs or filter programs by their IDs.

Example 
# get all programs in the workspace
programs = client.programs.get_programs()

# get several programs by their ids
filtered = client.programs.get_program_by_ids(['prog1_uuid', 'prog2_uuid'])

Methods:

Name Description
get_programs

Retrieve all programs available in the workspace.
get_programs_by_ids

Retrieve a list of Program objects whose IDs match the provided list.
create_program

Create a new program in the workspace.
update_program

Update an existing program.
Source code in kalbio/programs.py 
60
61
def __init__(self, client: KaleidoscopeClient):
    self._client = client

get_programs cached 

get_programs() -> list[Program]

Retrieve all programs available in the workspace.

This method caches its values.

Returns:

Type Description
list[Program]

List[Program]: A list of Program objects in the workspace.
Note

If an exception occurs during the API request, it logs the error, clears the cache, and returns an empty list.

Source code in kalbio/programs.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@lru_cache
def get_programs(self) -> List[Program]:
    """Retrieve all programs available in the workspace.

    This method caches its values.

    Returns:
        List[Program]: A list of Program objects in the workspace.

    Note:
        If an exception occurs during the API request, it logs the error,
        clears the cache, and returns an empty list.
    """
    resp = self._client._get("/programs")
    return TypeAdapter(List[Program]).validate_python(resp)

get_programs_by_ids 

get_programs_by_ids(ids: list[str]) -> list[Program]

Retrieve a list of Program objects whose IDs match the provided list.

Parameters:

Name Type Description Default
ids list[str]

A list of program IDs to filter by.

 required

Returns:

Type Description
list[Program]

List[Program]: A list of Program instances with IDs found in ids.
Source code in kalbio/programs.py 
79
80
81
82
83
84
85
86
87
88
89
def get_programs_by_ids(self, ids: List[str]) -> List[Program]:
    """Retrieve a list of Program objects whose IDs match the provided list.

    Args:
        ids (List[str]): A list of program IDs to filter by.

    Returns:
        List[Program]: A list of Program instances with IDs found in ids.
    """
    programs = self.get_programs()
    return [program for program in programs if program.id in ids]

create_program 

create_program(title: str) -> Program

Create a new program in the workspace.

Parameters:

Name Type Description Default
title str

The title of the program to create.

 required

Returns:

Name Type Description
Program Program

The created Program object.

Raises:

Type Description
KalbioAPIError

If the API request fails (e.g. validation error).
Source code in kalbio/programs.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def create_program(self, title: str) -> Program:
    """Create a new program in the workspace.

    Args:
        title (str): The title of the program to create.

    Returns:
        Program: The created Program object.

    Raises:
        KalbioAPIError: If the API request fails (e.g. validation error).
    """
    resp = self._client._post("/programs", {"title": title})
    self.get_programs.cache_clear()
    return Program(**resp)

update_program 

update_program(program_id: str, title: str) -> Program

Update an existing program.

Parameters:

Name Type Description Default
program_id str

The UUID of the program to update.

 required
title str

The new title for the program.

 required

Returns:

Name Type Description
Program Program

The updated Program object.

Raises:

Type Description
KalbioAPIError

If the API request fails (e.g. validation error).
Source code in kalbio/programs.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def update_program(self, program_id: str, title: str) -> Program:
    """Update an existing program.

    Args:
        program_id (str): The UUID of the program to update.
        title (str): The new title for the program.

    Returns:
        Program: The updated Program object.

    Raises:
        KalbioAPIError: If the API request fails (e.g. validation error).
    """
    resp = self._client._put(f"/programs/{program_id}", {"title": title})
    self.get_programs.cache_clear()
    return Program(**resp)