Workspace

workspace

Provides models and services for managing workspaces in the Kaleidoscope system.

This module contains data models for workspaces, workspace users, workspace groups, and workspace events, along with a service class for interacting with workspace-related API endpoints.

Classes:

Name	Description
WorkspaceAccessLevelEnum	Enumeration of possible access levels for workspace users.
Workspace	Model representing a workspace with its basic metadata.
WorkspaceUser	Model representing a user within a workspace, including access level.
WorkspaceGroup	Model representing a group of users within a workspace.
WorkspaceEvent	Model representing an event that occurred within a workspace.
WorkspaceService	Service class providing methods to interact with workspace API endpoints.

Example

    # get an instance of the workspace
    workspace = client.workspace.get_workspace()

    # get all members in the workspace
    members = client.workspace.get_members()

    # get all events, with search criteria
    events = client.workspace.get_events(event_types=["create", "update"])

WorkspaceAccessLevelEnum

Bases: str, Enum

Enumeration of possible access levels for workspace users.

Attributes:

Name	Type	Description
ADMIN		Administrator access with full privileges.
TEAM_MEMBER		Regular team member access.
GUEST		Guest access with limited privileges.
VIEWER		Read-only viewer access.
DEACTIVATED		Deactivated user status.

Workspace

Bases: _KaleidoscopeBaseModel

A model representing a workspace in the Kaleidoscope system.

This class extends _KaleidoscopeBaseModel and provides a structured representation of a workspace with its associated metadata and utility methods for serialization and string representation.

Attributes:

Name	Type	Description
id	str	UUID of the workspace
workspace_name	str	The name identifier for the workspace.

WorkspaceUser

Bases: _KaleidoscopeBaseModel

Represents a user within a workspace with their access permissions and contact information.

This class models a workspace user, storing their identification, name preferences, access level, and email address. It inherits from _KaleidoscopeBaseModel and provides utility methods for serialization and string representation.

Attributes:

Name	Type	Description
full_name	str | None	The user's full legal or registered name.
preferred_name	str | None	The name the user prefers to be called.
access_level	WorkspaceAccessLevelEnum	The user's permission level within the workspace.
email	str	The user's email address for communication and identification.

WorkspaceGroup

Bases: _KaleidoscopeBaseModel

Represents a workspace group in the Kaleidoscope system.

A WorkspaceGroup is a collection of users and programs that are organized together under a common group name and associated email address.

Attributes:

Name	Type	Description
group_name	str	The name of the workspace group.
user_ids	list[str]	A list of user IDs that belong to this workspace group.
program_ids	list[str]	A list of program IDs associated with this workspace group.
email	str	The email address associated with this workspace group.

WorkspaceEvent

Bases: _KaleidoscopeBaseModel

Represents a workspace event in the Kaleidoscope system.

This class models events that occur within a workspace, such as user actions, resource modifications, or system-generated events. It inherits from _KaleidoscopeBaseModel and provides methods for serialization and representation.

Attributes:

Name	Type	Description
full_name	str	The full name of the user associated with the event.
preferred_name	str | None	The preferred name of the user, if available.
is_bot	bool	Flag indicating whether the event was triggered by a bot.
event_attrs	dict	Additional attributes specific to the event type.
created_at	datetime	Timestamp when the event was created.
resource_id	str | None	ID of the resource associated with the event, if applicable.
resource_type	str | None	Type of the resource associated with the event, if applicable.
event_type	str	The type/category of the event.
event_type_version	int	Version number of the event type schema.
event_user_id	str	The unique identifier of the user who triggered the event.
parent_bulk_event_id	str	ID of the parent event if this is part of a bulk operation.
is_bulk	bool	Flag indicating whether this is a bulk event.

WorkspaceService

WorkspaceService(client: KaleidoscopeClient)

Service class for managing workspace-related operations in Kaleidoscope.

This service provides methods to retrieve workspace information, members, groups, and events. It uses caching (via lru_cache) for frequently accessed data like workspace details, members, and groups to improve performance.

Example

# get an instance of the workspace
workspace = client.workspace.get_workspace()

# get all members in the workspace
members = client.workspace.get_members()

# get all events, with search criteria
events = client.workspace.get_events(event_types=["create", "update"])

Note

Cached methods (get_workspace, get_members, get_groups) will automatically clear their cache on error to ensure stale data is not returned on subsequent calls.

Classes:

Name	Description
EventsQuery	TypedDict for workspace events query parameters.

Methods:

Name	Description
get_workspace	Retrieves the authenticated workspace.
get_members	Retrieves the members of the authenticated workspace.
get_members_by_ids	Retrieves a list of WorkspaceUser objects whose IDs match the provided list.
get_groups	Retrieves the groups of the authenticated workspace.
get_groups_by_ids	Retrieves a list of WorkspaceGroup objects whose IDs match the provided list.
get_events	Searches for events using the provided query parameters.

Source code in kalpy/workspace.py

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

EventsQuery

Bases: TypedDict

TypedDict for workspace events query parameters.

Attributes:

Name	Type	Description
page	int | None	The page number for pagination.
page_size	int | None	The number of items per page.
event_types	list[str]	List of event types to filter by.
resource_type	str	The type of resource to filter by.
event_user_ids	list[str]	List of user IDs to filter events by.
after_date	datetime	Filter events occurring after this date.
before_date	datetime	Filter events occurring before this date.

get_workspace cached

get_workspace() -> Workspace | None

Retrieves the authenticated workspace.

This method caches its values.

Returns:

Type	Description
Workspace | None	The active workspace, or None if an error occurs.

Source code in kalpy/workspace.py

@lru_cache
def get_workspace(self) -> Workspace | None:
    """Retrieves the authenticated workspace.

    This method caches its values.

    Returns:
        (Workspace | None): The active workspace, or None if an error occurs.
    """
    try:
        resp = self._client._get("/workspaces/active")
        return Workspace.model_validate(resp)
    except Exception as e:
        _logger.error(f"Error fetching workspace: {e}")
        self.get_workspace.cache_clear()
        return None

get_members cached

get_members() -> list[WorkspaceUser]

Retrieves the members of the authenticated workspace.

This method caches its values.

Returns:

Type	Description
list[WorkspaceUser]	List[WorkspaceUser]: The users 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/workspace.py

@lru_cache
def get_members(self) -> List[WorkspaceUser]:
    """Retrieves the members of the authenticated workspace.

    This method caches its values.

    Returns:
        List[WorkspaceUser]: The users 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("/workspaces/members")
        return TypeAdapter(List[WorkspaceUser]).validate_python(resp)
    except Exception as e:
        _logger.error(f"Error fetching members: {e}")
        self.get_members.cache_clear()
        return []

get_members_by_ids

get_members_by_ids(ids: list[str]) -> list[WorkspaceUser]

Retrieves a list of WorkspaceUser objects whose IDs match the provided list.

Parameters:

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

Returns:

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

Source code in kalpy/workspace.py

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

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

    Returns:
        List[WorkspaceUser]: A list of WorkspaceUser instances with IDs found in ids.
    """
    return [member for member in self.get_members() if member.id in ids]

get_groups cached

get_groups() -> list[WorkspaceGroup]

Retrieves the groups of the authenticated workspace.

This method caches its values.

Returns:

Type	Description
list[WorkspaceGroup]	List[WorkspaceGroup]: The groups 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/workspace.py

@lru_cache
def get_groups(self) -> List[WorkspaceGroup]:
    """Retrieves the groups of the authenticated workspace.

    This method caches its values.

    Returns:
        List[WorkspaceGroup]: The groups 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("/workspaces/groups")
        return TypeAdapter(List[WorkspaceGroup]).validate_python(resp)
    except Exception as e:
        _logger.error(f"Error fetching groups: {e}")
        self.get_groups.cache_clear()
        return []

get_groups_by_ids

get_groups_by_ids(ids: list[str]) -> list[WorkspaceGroup]

Retrieves a list of WorkspaceGroup objects whose IDs match the provided list.

Parameters:

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

Returns:

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

Source code in kalpy/workspace.py

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

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

    Returns:
        List[WorkspaceGroup]: A list of WorkspaceGroup instances with IDs found in ids.
    """
    return [group for group in self.get_groups() if group.id in ids]

get_events

get_events(**params: Unpack[EventsQuery]) -> list[WorkspaceEvent]

Searches for events using the provided query parameters.

Parameters:

Name	Type	Description	Default
**params	Unpack[EventsQuery]	Keyword arguments representing search criteria. Non-string values will be JSON-encoded before being sent.	{}

Returns:

Type	Description
list[WorkspaceEvent]	list[WorkspaceEvent]: A list of events matching the search criteria.
list[WorkspaceEvent]	Returns an empty list if the response is empty.

Note

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

Source code in kalpy/workspace.py

def get_events(self, **params: Unpack[EventsQuery]) -> List[WorkspaceEvent]:
    """Searches for events using the provided query parameters.

    Args:
        **params (Unpack[EventsQuery]): Keyword arguments representing search criteria. Non-string values will be JSON-encoded before being sent.

    Returns:
        list[WorkspaceEvent]: A list of events matching the search criteria.
        Returns an empty list if the response is empty.

    Note:
        If an exception occurs during the API request, it logs the error and returns an empty list.
    """
    try:
        client_params = {
            key: (value if isinstance(value, str) else json.dumps(value))
            for key, value in params.items()
        }
        resp = self._client._get("/workspaces/events", client_params)
        if resp is None:
            return []

        return resp
    except Exception as e:
        _logger.error(f"Error fetching events: {e}")
        return []