Labels

labels

Module for managing task labels in Kaleidoscope.

This module provides classes and services for working with task labels, including retrieval and filtering of labels from the Kaleidoscope workspace.

Classes:

Name	Description
Label	Represents a task label with an ID and name.
LabelsService	Service class for interacting with label-related API endpoints.

Label

Bases: _KaleidoscopeBaseModel

A class representing a label in the Kaleidoscope system.

This class extends _KaleidoscopeBaseModel and provides functionality for managing label data including serialization and string representations.

Attributes:

Name	Type	Description
label_name	str	The name of the label.

LabelsService

LabelsService(client: KaleidoscopeClient)

Service class for managing and retrieving task labels from Kaleidoscope.

This service provides methods to fetch labels from the Kaleidoscope workspace and filter them by specific criteria. It uses caching to optimize repeated label retrieval requests.

Example

# get all labels
all_labels = client.labels.get_labels()

# get labels by id
specific_labels = client.labels.get_labels_by_ids(['id1', 'id2'])

Methods:

Name	Description
get_labels	Retrieve the task labels defined in the workspace.
get_labels_by_ids	Retrieve a list of Label objects whose IDs match the provided list.

Source code in kalpy/labels.py

def __init__(self, client: KaleidoscopeClient):
    self._client = client

get_labels cached

get_labels() -> list[Label]

Retrieve the task labels defined in the workspace.

This method caches its values.

Returns:

Type	Description
list[Label]	List[Label]: The labels 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 kalpy/labels.py

@lru_cache
def get_labels(self) -> List[Label]:
    """Retrieve the task labels defined in the workspace.

    This method caches its values.

    Returns:
        List[Label]: The labels in the workspace.

    Note:
        If an exception occurs during the API request, it logs the error,
        clears the cache, and returns an empty list.
    """
    try:
        resp = self._client._get("/activity_labels")
        return TypeAdapter(List[Label]).validate_python(resp)
    except Exception as e:
        _logger.error(f"Error fetching labels: {e}")
        self.get_labels.cache_clear()
        return []

get_labels_by_ids

get_labels_by_ids(ids: list[str]) -> list[Label]

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

Parameters:

Name	Type	Description	Default
ids	list[str]	A list of label IDs to filter by.	required

Returns:

Type	Description
list[Label]	List[Label]: A list of Label instances with IDs found in ids.

Source code in kalpy/labels.py

def get_labels_by_ids(self, ids: List[str]) -> List[Label]:
    """Retrieve a list of Label objects whose IDs match the provided list.

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

    Returns:
        List[Label]: A list of Label instances with IDs found in ids.
    """
    return [label for label in self.get_labels() if label.id in ids]