kalbio 0.2.0__py3-none-any.whl

kalbio/exports.py

@@ -0,0 +1,126 @@
+"""
+Service class for handling data exports from Kaleidoscope.
+
+This class provides methods to export and download data from the Kaleidoscope API,
+specifically for pulling record search data and saving it as CSV files.
+
+Classes:
+    ExportsService: Service class for exporting and downloading record search data as CSV.
+
+Example:
+    ```python
+        # Pull data and download as CSV
+        file_path = client.exports_service.pull_data(
+            filename="my_export.csv",
+            entity_slice_id="some-uuid",
+            download_path="/path/to/downloads",
+            search_text="example"
+        )
+    ```
+"""
+
+from typing import Optional
+from kalbio.client import KaleidoscopeClient
+
+
+class ExportsService:
+    """Service class for handling data exports from Kaleidoscope.
+
+    This class provides methods to export and download data from the Kaleidoscope API,
+    specifically for pulling record search data and saving it as CSV files.
+
+    Example:
+        ```python
+        # Pull data and download as CSV
+        file_path = client.exports_service.pull_data(
+            filename="my_export.csv",
+            entity_slice_id="some-uuid",
+            download_path="/path/to/downloads",
+            search_text="example"
+        )
+        ```
+    """
+
+    def __init__(self, client: "KaleidoscopeClient"):
+        self._client = client
+
+    def pull_data(
+        self,
+        filename: str,
+        entity_slice_id: str,
+        download_path: Optional[str] = None,
+        record_view_id: Optional[str] = None,
+        view_field_ids: Optional[str] = None,
+        identifier_ids: Optional[str] = None,
+        record_set_id: Optional[str] = None,
+        program_id: Optional[str] = None,
+        operation_id: Optional[str] = None,
+        record_set_filters: Optional[str] = None,
+        view_field_filters: Optional[str] = None,
+        view_field_sorts: Optional[str] = None,
+        entity_field_filters: Optional[str] = None,
+        entity_field_sorts: Optional[str] = None,
+        search_text: Optional[str] = None,
+    ) -> str | None:
+        """Pull record search data and download it as a CSV file.
+
+        This method interacts with the Kaleidoscope API to export records as a CSV file based on the provided parameters.
+        It supports filtering, sorting, and searching records, and allows specifying various identifiers and filters
+        to customize the export.
+
+        Args:
+            filename (str): The name of the CSV file to be downloaded.
+            entity_slice_id (str): The ID of the entity slice to export records from.
+            download_path (str, optional): The directory path where the CSV file will be saved. Defaults to None (uses '/tmp').
+            record_view_id (str, optional): The ID of the record view to filter records. Defaults to None.
+            view_field_ids (str, optional): Comma-separated IDs of view fields to include in the export. Defaults to None.
+            identifier_ids (str, optional): Comma-separated IDs of identifiers to filter records. Defaults to None.
+            record_set_id (str, optional): The ID of the record set to filter records. Defaults to None.
+            program_id (str, optional): The ID of the program to filter records. Defaults to None.
+            operation_id (str, optional): The ID of the operation to filter records. Defaults to None.
+            record_set_filters (str, optional): Filters to apply to the record set. Defaults to None.
+            view_field_filters (str, optional): Filters to apply to view fields. Defaults to None.
+            view_field_sorts (str, optional): Sorting options for view fields. Defaults to None.
+            entity_field_filters (str, optional): Filters to apply to entity fields. Defaults to None.
+            entity_field_sorts (str, optional): Sorting options for entity fields. Defaults to None.
+            search_text (str, optional): Text to search within records. Defaults to None.
+
+        Returns:
+            (str | None): The file path of the downloaded CSV file, or None if not successful.
+
+        API Reference:
+            https://kaleidoscope.readme.io/reference/get_records-export-csv
+        """
+
+        params = {
+            "filename": filename,
+            "entity_slice_id": entity_slice_id,
+        }
+
+        optional_params = {
+            "record_view_id": record_view_id,
+            "view_field_ids": view_field_ids,
+            "identifier_ids": identifier_ids,
+            "record_set_id": record_set_id,
+            "program_id": program_id,
+            "operation_id": operation_id,
+            "record_set_filters": record_set_filters,
+            "view_field_filters": view_field_filters,
+            "view_field_sorts": view_field_sorts,
+            "entity_field_filters": entity_field_filters,
+            "entity_field_sorts": entity_field_sorts,
+            "search_text": search_text,
+        }
+
+        params.update(
+            {key: value for key, value in optional_params.items() if value is not None}
+        )
+
+        url = "/records/export/csv"
+        file = self._client._get_file(
+            url,
+            f"{download_path if download_path else "/tmp"}/{filename}",
+            params,
+        )
+
+        return file

kalbio/helpers.py

@@ -0,0 +1,52 @@
+"""Module of helper methods for the Kaleidoscope Python Client.
+
+This module provides utility functions for data transformation and other helper tasks.
+Currently, it includes functionality to map field IDs to human-readable field names.
+
+Functions:
+    export_data: Transforms data records by mapping field IDs to field names.
+
+Example:
+    ```python
+    from kalbio.helpers import export_data
+
+    # Transform raw data with field IDs to data with field names
+    processed_data = export_data(client, raw_data)
+    ```
+"""
+
+from kalbio.client import KaleidoscopeClient
+from typing import Any, Dict, List
+
+
+def export_data(
+    client: KaleidoscopeClient, data: List[Dict[str, Any]]
+) -> List[Dict[str, Any]]:
+    """Transform a list of data records by mapping field IDs to their corresponding field names.
+
+    This function takes raw data records where keys are field IDs and converts them into
+    records where keys are human-readable field names. It uses the KaleidoscopeClient to
+    retrieve field metadata and perform the mapping. If a field ID is not found in the
+    metadata, the original ID is preserved as the key.
+
+    Args:
+        client (KaleidoscopeClient): The client instance containing field metadata used
+            to map field IDs to field names.
+        data (List[Dict[str, Any]]): A list of records, each represented as a dictionary
+            mapping field IDs to their values.
+
+    Returns:
+        (List[Dict[str, Any]]): A list of transformed records, each represented as a dictionary
+            mapping field names (as keys) to their values.
+    """
+    key_fields = client.entity_fields.get_key_fields()
+    data_fields = client.entity_fields.get_data_fields()
+
+    id_to_field = {item.id: item for item in key_fields + data_fields}
+    return [
+        {
+            (id_to_field[id].field_name if id in id_to_field else id): value
+            for id, value in record.items()
+        }
+        for record in data
+    ]

kalbio/imports.py

@@ -0,0 +1,89 @@
+"""Service class for handling data imports into Kaleidoscope workspace.
+
+This module provides the `ImportsService` class, which facilitates pushing data records
+into the Kaleidoscope system. It supports flexible data import operations, allowing
+organization by experiments, programs, and data sources.
+
+Classes:
+    ImportsService: Service for handling data imports into the Kaleidoscope workspace, providing methods to push records organized by source, experiment, program, record views, and set names.
+
+Example:
+    ```python
+    key_fields = ["id", "timestamp"]
+    records = [
+        {"id": "001", "timestamp": "2024-01-01", "value": 42.5, "status": "active"},
+        {"id": "002", "timestamp": "2024-01-02", "value": 38.7, "status": "pending"}
+    ]
+    # Push data to a specific source and experiment
+    response = client.imports.push_data(
+        key_field_names=key_fields,
+        data=records,
+        source_id="data_source_123",
+        operation_id="exp_456",
+        set_name="january_batch"
+    )
+    ```
+"""
+
+from typing import Any, Optional
+from kalbio.client import KaleidoscopeClient
+
+
+class ImportsService:
+    """Service class for handling data imports into Kaleidoscope workspace.
+
+    This service provides functionality to push data records into the workspace,
+    with support for organizing data by sources, experiments, programs, and record views.
+
+    Methods:
+        push_data: Imports data records into the workspace with various organizational options.
+    """
+
+    def __init__(self, client: KaleidoscopeClient):
+        self._client = client
+
+    def push_data(
+        self,
+        key_field_names: list[str],
+        data: list[dict[str, Any]],
+        source_id: Optional[str] = None,
+        operation_id: Optional[str] = None,
+        program_id: Optional[str] = None,
+        record_view_ids: Optional[list[str]] = [],
+        set_name: Optional[str] = None,
+    ) -> Any:
+        """Import data into the workspace.
+
+        Sends a list of records, each represented as a dictionary of field names and values,
+        to the Kaleidoscope workspace.
+
+        Args:
+            key_field_names (list[str]): List of field names that serve as keys for the records.
+            data (list[dict[str, Any]]): List of records to import, each as a dictionary mapping field names to values.
+            source_id (str, optional): Identifier for the data source. If provided, data is imported under this source.
+            operation_id (str, optional): Identifier for the experiment. If provided, data is imported into this specific experiment.
+            program_id (str, optional): Identifier for the program. If provided, data is imported under this program.
+            record_view_ids (list[str], optional): List of record view IDs to associate with the imported data.
+            set_name (str, optional): Name of the set to which the imported data belongs.
+
+        Returns:
+            Any: Response object from the client's POST request to the import endpoint.
+        """
+        payload = {
+            "key_field_names": key_field_names,
+            "data": data,
+            "record_view_ids": record_view_ids,
+        }
+
+        if program_id:
+            payload["program_id"] = program_id
+        if operation_id:
+            payload["operation_id"] = operation_id
+        if set_name:
+            payload["set_name"] = set_name
+
+        url = "/push/imports"
+        if source_id:
+            url = url + f"/{source_id}"
+
+        return self._client._post(url, payload)

kalbio/labels.py

@@ -0,0 +1,88 @@
+"""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:
+    Label: Represents a task label with an ID and name.
+    LabelsService: Service class for interacting with label-related API endpoints.
+"""
+
+import logging
+
+from functools import lru_cache
+from typing import List
+from kalbio._kaleidoscope_model import _KaleidoscopeBaseModel
+from kalbio.client import KaleidoscopeClient
+from pydantic import TypeAdapter
+
+_logger = logging.getLogger(__name__)
+
+
+class Label(_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:
+        label_name (str): The name of the label.
+    """
+
+    label_name: str
+
+    def __str__(self):
+        return f"{self.label_name}"
+
+
+class LabelsService:
+    """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:
+        ```python
+        # get all labels
+        all_labels = client.labels.get_labels()
+
+        # get labels by id
+        specific_labels = client.labels.get_labels_by_ids(['id1', 'id2'])
+        ```
+    """
+
+    def __init__(self, client: KaleidoscopeClient):
+        self._client = client
+
+    @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 []
+
+    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]

kalbio/programs.py

@@ -0,0 +1,96 @@
+"""Programs module for interacting with Kaleidoscope programs/experiments.
+
+The service allows users to retrieve all available programs in a workspace
+and filter programs by specific IDs.
+
+Classes:
+    Program: Data model for a Kaleidoscope program/experiment.
+    ProgramsService: Service for managing program retrieval operations.
+
+Example:
+    ```python
+    # 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'])
+    ```
+"""
+
+import logging
+from functools import lru_cache
+from kalbio._kaleidoscope_model import _KaleidoscopeBaseModel
+from kalbio.client import KaleidoscopeClient
+from pydantic import TypeAdapter
+from typing import List
+
+_logger = logging.getLogger(__name__)
+
+
+class Program(_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:
+        title (str): The title/name of the program.
+    """
+
+    title: str
+
+    def __str__(self):
+        return f"{self.title}"
+
+
+class ProgramsService:
+    """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:
+        ```python
+        # 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'])
+        ```
+    """
+
+    def __init__(self, client: KaleidoscopeClient):
+        self._client = client
+
+    @lru_cache
+    def get_programs(self) -> List[Program]:
+        """Retrieve all programs (experiments) available in the workspace.
+
+        This method caches its values.
+
+        Returns:
+            List[Program]: A list of Program objects representing the experiments 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("/programs")
+            return TypeAdapter(List[Program]).validate_python(resp)
+        except Exception as e:
+            _logger.error(f"Error fetching programs: {e}")
+            self.get_programs.cache_clear()
+            return []
+
+    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]

kalbio/property_fields.py

@@ -0,0 +1,81 @@
+"""Service for managing property field definitions in Kaleidoscope.
+
+This module provides classes and services for working with property fields, which define
+named properties with descriptions and data types used to structure and validate data
+within the Kaleidoscope framework.
+
+Classes:
+    PropertyField: Represents a single property field with name, description, and type.
+    PropertyFieldsService: Service for retrieving and managing property field definitions.
+
+Example:
+    ```python
+    fields = client.property_fields.get_property_fields()
+    for field in fields:
+        print(f"{field.property_name}: {field.field_type}")
+    ```
+"""
+
+import logging
+from functools import lru_cache
+from typing import List
+from pydantic import TypeAdapter
+from kalbio._kaleidoscope_model import _KaleidoscopeBaseModel
+from kalbio.client import KaleidoscopeClient
+from kalbio.entity_fields import DataFieldTypeEnum
+
+_logger = logging.getLogger(__name__)
+
+
+class PropertyField(_KaleidoscopeBaseModel):
+    """Represents a property field in the Kaleidoscope system.
+
+    A PropertyField defines a named property with a description and data type,
+    used to structure and validate data within the Kaleidoscope framework.
+
+    Attributes:
+        property_name (str): The name of the property field.
+        property_description (str): A human-readable description of the property.
+        field_type (DataFieldTypeEnum): The data type of the field.
+    """
+
+    property_name: str
+    property_description: str
+    field_type: DataFieldTypeEnum
+
+    def __str__(self):
+        return f"{self.property_name}"
+
+
+class PropertyFieldsService:
+    """Service class for managing property fields in Kaleidoscope.
+
+    This service provides methods to retrieve and manage property field definitions
+    from the Kaleidoscope API. It uses caching to optimize repeated requests for
+    property field data.
+
+    """
+
+    def __init__(self, client: KaleidoscopeClient):
+        self._client = client
+
+    @lru_cache
+    def get_property_fields(self) -> List[PropertyField]:
+        """Retrieve the property fields from the client.
+
+        This method caches its values.
+
+        Returns:
+            List[PropertyField]: A list of PropertyField objects representing the property fields 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("/property_fields")
+            return TypeAdapter(List[PropertyField]).validate_python(resp)
+        except Exception as e:
+            _logger.error(f"Error fetching property fields: {e}")
+            self.get_property_fields.cache_clear()
+            return []