kalbio 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

kalbio/__init__.py

@@ -1 +1,10 @@
-__version__ = "0.2.0"
+from importlib.metadata import version, PackageNotFoundError
+
+from kalbio.client import KaleidoscopeClient
+
+try:
+    __version__ = version("kalbio")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+__all__ = ["KaleidoscopeClient"]

kalbio/activities.py

@@ -1,6 +1,6 @@
 """Activities Module for Kaleidoscope API Client.
 
-This module provides comprehensive functionality for managing activities (tasks, experiments,
+This module provides functionality for managing activities (tasks, experiments,
 projects, stages, milestones, and design cycles) within the Kaleidoscope platform. It includes
 models for activities, activity definitions, and properties, as well as service classes for
 performing CRUD operations and managing activity workflows.
@@ -65,7 +65,7 @@ from kalbio.entity_fields import DataFieldTypeEnum
 from kalbio.programs import Program
 from kalbio.labels import Label
 from kalbio.workspace import WorkspaceUser, WorkspaceGroup
-from typing import Any, BinaryIO, List, Literal, Optional, Union
+from typing import Any, BinaryIO, List, Literal, Optional, TypeAlias, Union
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -153,7 +153,7 @@ class ActivityStatusEnum(str, Enum):
     DONE = "done"
 
 
-type ActivityType = Union[
+ActivityType: TypeAlias = Union[
     Literal["task"],
     Literal["experiment"],
     Literal["project"],
@@ -671,7 +671,7 @@ class Activity(_KaleidoscopeBaseModel):
             setattr(self, k, v)
 
 
-type ActivityIdentifier = Union[Activity, str]
+ActivityIdentifier: TypeAlias = Union[Activity, str]
 """Identifier class for Activity
 
 Activities are able to be identified by:
@@ -681,7 +681,7 @@ Activities are able to be identified by:
 * UUID
 """
 
-type DefinitionIdentifier = Union[ActivityDefinition, str]
+DefinitionIdentifier: TypeAlias = Union[ActivityDefinition, str]
 """Identifier class for ActivityDefinition
 
 ActivityDefinitions are able to be identified by:
@@ -876,12 +876,11 @@ class ActivitiesService:
 
         try:
             payload = {
-                "program_ids": program_ids,
                 "title": title,
                 "activity_type": activity_type,
                 "definition_id": self._resolve_definition_id(activity_definition_id),
-                "record_ids": [],
-                "assigned_user_ids": assigned_user_ids,
+                "program_ids": program_ids if program_ids else [],
+                "assigned_user_ids": assigned_user_ids if assigned_user_ids else [],
                 "start_date": start_date.isoformat() if start_date else None,
                 "duration": duration,
             }

kalbio/client.py

@@ -59,8 +59,8 @@ Any file retrieved by the `KaleidoscopeClient` must be of one the above types"""
 TIMEOUT_MAXIMUM = 10
 """Maximum timeout for API requests in seconds."""
 
-_api_key = os.getenv("KALEIDOSCOPE_API_CLIENT_ID")
-_api_secret = os.getenv("KALEIDOSCOPE_API_CLIENT_SECRET")
+_env_client_id = os.getenv("KALEIDOSCOPE_API_CLIENT_ID")
+_env_client_secret = os.getenv("KALEIDOSCOPE_API_CLIENT_SECRET")
 
 
 class _TokenResponse(BaseModel):
@@ -107,21 +107,36 @@ class KaleidoscopeClient:
         )
         # Use the client to interact with various services
         programs = client.activities.get_activities()
+
+        # For applications behind Google Cloud IAP:
+        client = KaleidoscopeClient(
+            client_id="your_api_client_id",
+            client_secret="your_api_client_secret",
+            iap_client_id="your_iap_client_id.apps.googleusercontent.com"
+        )
         ```
     """
 
     _client_id: str
     _client_secret: str
+    _additional_headers: dict
+    _iap_client_id: Optional[str]
 
-    _refresh_token: str
-    _access_token: str
-    _refresh_before: datetime
+    _refresh_token: str = None
+    _access_token: str = None
+    _auth_refresh_before: Optional[datetime] = None
+
+    _iap_token: Optional[str] = None
+    _iap_refresh_before: Optional[datetime] = None
 
     def __init__(
         self,
-        client_id: Optional[str] = _api_key,
-        client_secret: Optional[str] = _api_secret,
+        client_id: Optional[str] = _env_client_id,
+        client_secret: Optional[str] = _env_client_secret,
         url: str = PROD_API_URL,
+        additional_headers: dict = {},
+        iap_client_id: Optional[str] = None,
+        verify_ssl: bool = True,
     ):
         """Initialize the Kaleidoscope API client.
 
@@ -133,6 +148,9 @@ class KaleidoscopeClient:
             client_secret (str): The API client secret for authentication.
             url (Optional[str]): The base URL for the API. Defaults to the production
                 API URL if not provided.
+            iap_client_id (Optional[str]): The OAuth client ID for Google Cloud
+                Identity-Aware Proxy. If provided, the client will automatically
+                fetch and refresh IAP tokens. Requires the `google-auth` package.
 
         Example:
             ```python
@@ -141,6 +159,13 @@ class KaleidoscopeClient:
 
             # Or rely on environment variables KALEIDOSCOPE_API_CLIENT_ID/SECRET
             client = KaleidoscopeClient()
+
+            # For applications behind Google Cloud IAP
+            client = KaleidoscopeClient(
+                client_id="id",
+                client_secret="secret",
+                iap_client_id="your_iap_client_id.apps.googleusercontent.com"
+            )
             ```
         """
         if client_id is None:
@@ -183,9 +208,35 @@ class KaleidoscopeClient:
 
         self._client_id = client_id
         self._client_secret = client_secret
-        self._get_auth_token()
+        self.additional_headers = additional_headers
+        self._iap_client_id = iap_client_id
+        self._verify_ssl = verify_ssl
+
+    def _refresh_iap_token(self):
+        """Fetch or refresh the IAP ID token.
+
+        Uses google-auth to obtain an ID token for the configured IAP client ID.
+        Supports both service account credentials and user credentials from
+        `gcloud auth application-default login`.
+
+        Raises:
+            ImportError: If google-auth is not installed.
+            google.auth.exceptions.DefaultCredentialsError: If no valid credentials found.
+        """
+        try:
+            from google.auth.transport.requests import Request
+            from google.oauth2 import id_token
+        except ImportError:
+            raise ImportError(
+                "The 'google-auth' package is required for IAP authentication. "
+                "Install it with: pip install google-auth or re-install kalbio with the iap option: "
+                "pip install kalbio[iap]"
+            )
+        self._iap_token = id_token.fetch_id_token(Request(), self._iap_client_id)
+        # IAP tokens typically expire in 1 hour; refresh 10 minutes early
+        self._iap_refresh_before = datetime.now() + timedelta(minutes=50)
 
-    def _update_tokens(self, resp: _TokenResponse):
+    def _update_auth_tokens(self, resp: _TokenResponse):
         """Persist access and refresh tokens and compute the next refresh time.
 
         Args:
@@ -193,7 +244,7 @@ class KaleidoscopeClient:
         """
         self._access_token = resp.access_token
         self._refresh_token = resp.refresh_token
-        self._last_refreshed_at = datetime.now() + timedelta(
+        self._auth_refresh_before = datetime.now() + timedelta(
             seconds=resp.expires_in - (60 * 10)  # add a 10 minute buffer
         )
 
@@ -210,14 +261,16 @@ class KaleidoscopeClient:
                 "client_id": self._client_id,
                 "client_secret": self._client_secret,
             },
+            headers={**self._get_iap_headers(), **self.additional_headers},
             timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
         )
         if auth_resp.status_code >= 400:
             raise RuntimeError(
                 f"Could not connect to server with client_id {self._client_id}: {auth_resp.content}"
             )
 
-        self._update_tokens(_TokenResponse.model_validate(auth_resp.json()))
+        self._update_auth_tokens(_TokenResponse.model_validate(auth_resp.json()))
 
     def _refresh_auth_token(self):
         """Refresh the access token using the stored refresh token.
@@ -234,27 +287,54 @@ class KaleidoscopeClient:
                 "grant_type": "refresh_token",
                 "refresh_token": self._refresh_token,
             },
+            headers={**self._get_iap_headers(), **self.additional_headers},
             timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
         )
         if auth_resp.status_code >= 400:
             raise RuntimeError(f"Could not refresh access token: {auth_resp.content}")
 
-        self._update_tokens(_TokenResponse.model_validate(auth_resp.json()))
+        self._update_auth_tokens(_TokenResponse.model_validate(auth_resp.json()))
+
+    def _get_iap_headers(self) -> dict:
+        """Build IAP headers, refreshing tokens if needed.
+
+        Returns:
+            dict: HTTP header for IAP (Proxy-Authorization)
+        """
+        headers = {}
+        if self._iap_client_id:
+            if (
+                self._iap_refresh_before is None
+                or datetime.now() > self._iap_refresh_before
+            ):
+                self._refresh_iap_token()
+            headers["Authorization"] = f"Bearer {self._iap_token}"
+
+        return headers
 
     def _get_headers(self) -> dict:
         """Build authorization headers, refreshing tokens if needed.
 
         Returns:
-            dict: HTTP headers including `Authorization` and `Content-Type`.
+            dict: HTTP headers including `Authorization`, `Content-Type`,
+                and optionally `Proxy-Authorization` for IAP.
         """
-        if datetime.now() > self._last_refreshed_at:
+        if (
+            self._auth_refresh_before is None
+            or datetime.now() > self._auth_refresh_before
+        ):
             self._refresh_auth_token()
 
-        return {
+        headers = {
             "Content-Type": "application/json",
-            "Authorization": f"Bearer {self._access_token}",
+            "X-Kal-Authorization": f"Bearer {self._access_token}",
+            **self._get_iap_headers(),
+            **self.additional_headers,
         }
 
+        return headers
+
     def _post(self, url: str, payload: dict) -> Any:
         """Send a POST request to the specified URL with the given payload.
 
@@ -277,6 +357,7 @@ class KaleidoscopeClient:
             data=json.dumps(payload),
             headers=self._get_headers(),
             timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
         )
         if resp.status_code >= 400:
             print(f"POST {url} received {resp.status_code}: ", resp.content)
@@ -317,6 +398,7 @@ class KaleidoscopeClient:
             data=form_data,
             headers=self._get_headers(),
             timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
         )
         if resp.status_code >= 400:
             print(f"POST {url} received {resp.status_code}: ", resp.content)
@@ -346,6 +428,7 @@ class KaleidoscopeClient:
             data=json.dumps(payload),
             headers=self._get_headers(),
             timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
         )
         if resp.status_code >= 400:
             print(f"PUT {url} received {resp.status_code}: ", resp.content)
@@ -374,7 +457,12 @@ class KaleidoscopeClient:
         if params:
             url += "?" + urllib.parse.urlencode(params)
 
-        resp = requests.get(url, headers=self._get_headers(), timeout=TIMEOUT_MAXIMUM)
+        resp = requests.get(
+            url,
+            headers=self._get_headers(),
+            timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
+        )
         if resp.status_code >= 400:
             print(f"GET {url} received {resp.status_code}", resp.content)
             return None
@@ -412,7 +500,11 @@ class KaleidoscopeClient:
             url += "?" + urllib.parse.urlencode(params)
 
         resp = requests.get(
-            url, headers=self._get_headers(), stream=True, timeout=TIMEOUT_MAXIMUM
+            url,
+            headers=self._get_headers(),
+            stream=True,
+            timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
         )
         if resp.status_code >= 400:
             print(f"GET {url} received {resp.status_code}", resp.content)
@@ -452,7 +544,10 @@ class KaleidoscopeClient:
             url += "?" + urllib.parse.urlencode(params)
 
         resp = requests.delete(
-            url, headers=self._get_headers(), timeout=TIMEOUT_MAXIMUM
+            url,
+            headers=self._get_headers(),
+            timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
         )
         if resp.status_code >= 400:
             print(f"DELETE {url} received {resp.status_code}", resp.content)

kalbio/dashboards.py

@@ -21,11 +21,11 @@ from functools import lru_cache
 from kalbio._kaleidoscope_model import _KaleidoscopeBaseModel
 from kalbio.client import KaleidoscopeClient
 from pydantic import TypeAdapter
-from typing import List, Literal, Union
+from typing import List, Literal, TypeAlias, Union
 
 _logger = logging.getLogger(__name__)
 
-type DashboardType = Union[
+DashboardType: TypeAlias = Union[
     Literal["decision"],
     Literal["data"],
     Literal["chart"],

kalbio/entity_fields.py

@@ -41,7 +41,7 @@ from functools import lru_cache
 from kalbio._kaleidoscope_model import _KaleidoscopeBaseModel
 from kalbio.client import KaleidoscopeClient
 from pydantic import TypeAdapter
-from typing import List, Optional, Union
+from typing import List, Optional, TypeAlias, Union
 
 _logger = logging.getLogger(__name__)
 
@@ -151,7 +151,7 @@ class EntityField(_KaleidoscopeBaseModel):
         return f"{self.field_name}"
 
 
-type EntityFieldIdentifier = Union[EntityField, str]
+EntityFieldIdentifier: TypeAlias = Union[EntityField, str]
 """An Identifier Type for Entity Fields.
 
 An EntityField should be able to be identified by:

kalbio/exports.py

@@ -119,7 +119,7 @@ class ExportsService:
         url = "/records/export/csv"
         file = self._client._get_file(
             url,
-            f"{download_path if download_path else "/tmp"}/{filename}",
+            f"{download_path if download_path else '/tmp'}/{filename}",
             params,
         )
 

kalbio/programs.py

@@ -1,10 +1,10 @@
-"""Programs module for interacting with Kaleidoscope programs/experiments.
+"""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:
-    Program: Data model for a Kaleidoscope program/experiment.
+    Program: Data model for a Kaleidoscope program.
     ProgramsService: Service for managing program retrieval operations.
 
 Example:
@@ -64,12 +64,12 @@ class ProgramsService:
 
     @lru_cache
     def get_programs(self) -> List[Program]:
-        """Retrieve all programs (experiments) available in the workspace.
+        """Retrieve all programs available in the workspace.
 
         This method caches its values.
 
         Returns:
-            List[Program]: A list of Program objects representing the experiments in the workspace.
+            List[Program]: A list of Program objects in the workspace.
 
         Note:
             If an exception occurs during the API request, it logs the error,

kalbio/records.py

@@ -62,6 +62,7 @@ from typing import (
     Dict,
     List,
     Optional,
+    TypeAlias,
     TypedDict,
     Union,
     Unpack,
@@ -631,7 +632,7 @@ class Record(_KaleidoscopeBaseModel):
             setattr(self, k, v)
 
 
-type RecordIdentifier = Union[Record, str, dict[EntityFieldIdentifier, str]]
+RecordIdentifier: TypeAlias = Union[Record, str, dict[EntityFieldIdentifier, str]]
 """Identifier type for Record
 
 Record can be identified by:
@@ -1154,7 +1155,7 @@ class RecordsService:
         ]
         # fmt: on
 
-        resp = self._client._get(f"/records?record_ids={",".join(to_fetch)}") or []
+        resp = self._client._get(f"/records?record_ids={','.join(to_fetch)}") or []
         self._create_record_list(resp)
 
         ordered = [

{kalbio-0.2.1.dist-info → kalbio-0.2.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: kalbio
-Version: 0.2.1
+Version: 0.2.3
 Summary: Python client for kaleidoscope.bio
 License: MIT
 Author: Ahmed Elnaiem
@@ -11,6 +11,9 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: iap
+Requires-Dist: cachetools (>=6.2.5,<7.0.0)
+Requires-Dist: google-auth (>=2.0.0,<3.0.0) ; extra == "iap"
 Requires-Dist: pydantic (>=2.9.2,<3.0.0)
 Requires-Dist: requests (>=2.32.3,<3.0.0)
 Project-URL: Documentation, https://api.docs.kaleidoscope.bio
@@ -32,7 +35,6 @@ Kalbio is a Python Client library for building applications with the Kaleidoscop
 - **Intuitive Resource Management**: Clean, object-oriented interface for programs, activities, records, and more
 - **Advanced Search & Filtering**: Powerful query capabilities with type-safe filter operators
 - **File Upload Support**: Direct file upload to record fields with support for multiple file types
-- **Comprehensive Coverage**: Access all Kaleidoscope platform resources through a unified client
 - **Bulk Operations**: Import and export capabilities for efficient data management
 
 ## Requirements
@@ -147,13 +149,13 @@ with open("experiment_data.csv", "rb") as file:
     )
 ```
 
-### Comprehensive Resource Management
+### Resource Management
 
-Kalbio provides services for all Kaleidoscope resources:
+Kalbio provides services for the following Kaleidoscope resources:
 
 - **Programs**: Organize your work
 - **Activities**: Tasks, experiments, projects, etc.
-- **Records**: Structured data storage
+- **Records**: Structured entity records
 - **Entity Types**: Define your data schemas
 - **Entity Fields**: Manage field definitions
 - **Labels**: Tag and categorize
@@ -170,7 +172,7 @@ Once you have a client instance, you have access to:
 | ---------------------- | ------------------------------------------- |
 | `client.programs`      | Program management                          |
 | `client.activities`    | Activities (tasks, experiments, projects)   |
-| `client.records`       | Record CRUD operations                      |
+| `client.records`       | Entity record CRUD operations               |
 | `client.entity_types`  | Entity type definitions                     |
 | `client.entity_fields` | Field definitions (key fields, data fields) |
 | `client.labels`        | Label management                            |

kalbio-0.2.3.dist-info/RECORD

@@ -0,0 +1,19 @@
+kalbio/__init__.py,sha256=6Po_T4MM5m2qNTYgLe4E89C57OVwDaRQ9pXTJTuJsM4,240
+kalbio/_kaleidoscope_model.py,sha256=UnSpiubaEkoyOLjAmKzQGZdXOUMthuP0HiYU1Lo2sFM,4465
+kalbio/activities.py,sha256=UBvQGvQpuOirkWNX_3MNxNAstfo500PgJ6oVBf7HTCA,40654
+kalbio/client.py,sha256=C6r-yuHqlk-dAq55Ur9y7FrowhLvGSR2qzb5YPvf09k,20486
+kalbio/dashboards.py,sha256=Hj3mFjIBIualk5FXC1CLyLFbfvqGdYYLfdpFeigk1jw,9351
+kalbio/entity_fields.py,sha256=mqE4VP2g1-XR2vLUt1TIvX9Drv71NCCYPKBh03f0zO0,15201
+kalbio/entity_types.py,sha256=THXGbIV9dFU2DvIuDd7Q29onmEs9KdeqsB_tq6ZXmR4,6527
+kalbio/exports.py,sha256=IiAk4ZnjU59N4lrKeDRD60ZViOigR0QDd3XcNaWq5O0,5236
+kalbio/helpers.py,sha256=TBPVls1GzfUygDAwCldI5sXYTgBC2pEUSEU0OtrQi3I,1955
+kalbio/imports.py,sha256=s7LIETRQtT6MXEmsbIT2FwFJdE3eh25ujbs4ZFbWYns,3523
+kalbio/labels.py,sha256=Vy7PiZ8vFXIBbrCmdHyz7ANooO0-giTvTLH7WwU_Mo8,2704
+kalbio/programs.py,sha256=svYmZLhN2pwT9cAB8IfvyIbUmFnMVxcoUeeUxs_uESs,2951
+kalbio/property_fields.py,sha256=eCYzSnG-HQB6ECHFNpaGkpm3azHe-lDYVNJUpq5TOtc,2763
+kalbio/record_views.py,sha256=M3NEOhnN4JHA8ZO0I91L9pAVdVY0kmqSent3HehzFTI,7208
+kalbio/records.py,sha256=sQiGnXQaiS6VNj0n2mn8tw7u8kquHLhcAI5fpHjYL8U,40501
+kalbio/workspace.py,sha256=YpeLtzo3o8um_CQLyTT8GnvkF6I195y43JhNN2GmM0M,11670
+kalbio-0.2.3.dist-info/METADATA,sha256=VK7xMMAwxXl-v6kOdNMRisHf2hv3t1rrt74XmSCJb6o,7993
+kalbio-0.2.3.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+kalbio-0.2.3.dist-info/RECORD,,

kalbio-0.2.1.dist-info/RECORD

@@ -1,19 +0,0 @@
-kalbio/__init__.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
-kalbio/_kaleidoscope_model.py,sha256=UnSpiubaEkoyOLjAmKzQGZdXOUMthuP0HiYU1Lo2sFM,4465
-kalbio/activities.py,sha256=zvemwfuiPgTjhpMhzsHon7UselKmuqw9tWpM766m5F4,40621
-kalbio/client.py,sha256=a2NP-FfIbIuRXQ-19KSxcbjyvCpfSXdkUiypgp2-jh8,16822
-kalbio/dashboards.py,sha256=0P8lNiTmyaQj0y8B7AKf1VWU0qHuTUGJ_4xDVtr9jXA,9334
-kalbio/entity_fields.py,sha256=HnvOSE9C_UB59ioY5mB5Sn_V3OwnfRuYZ_IJtEw2vUY,15184
-kalbio/entity_types.py,sha256=THXGbIV9dFU2DvIuDd7Q29onmEs9KdeqsB_tq6ZXmR4,6527
-kalbio/exports.py,sha256=xFdNzajrGUlPZx6tNhgqiUg1lVnrayVQW12d-SmKWA4,5236
-kalbio/helpers.py,sha256=TBPVls1GzfUygDAwCldI5sXYTgBC2pEUSEU0OtrQi3I,1955
-kalbio/imports.py,sha256=s7LIETRQtT6MXEmsbIT2FwFJdE3eh25ujbs4ZFbWYns,3523
-kalbio/labels.py,sha256=Vy7PiZ8vFXIBbrCmdHyz7ANooO0-giTvTLH7WwU_Mo8,2704
-kalbio/programs.py,sha256=SKVJbF08Pp4r7dXfy9NNQnJRnSh-kOpDVdib197EWUM,3017
-kalbio/property_fields.py,sha256=eCYzSnG-HQB6ECHFNpaGkpm3azHe-lDYVNJUpq5TOtc,2763
-kalbio/record_views.py,sha256=M3NEOhnN4JHA8ZO0I91L9pAVdVY0kmqSent3HehzFTI,7208
-kalbio/records.py,sha256=BXuFCA90ViSMp_TtnWJYfQnJgH9Hz-5u4iT0wF0B1UM,40480
-kalbio/workspace.py,sha256=YpeLtzo3o8um_CQLyTT8GnvkF6I195y43JhNN2GmM0M,11670
-kalbio-0.2.1.dist-info/METADATA,sha256=hzK2SQ3YjZaTLsATC3a1cg1bGOMpm3ge9vVGNxRK1BU,7969
-kalbio-0.2.1.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-kalbio-0.2.1.dist-info/RECORD,,