cloudos_cli.interactive_session.interactive_session

Interactive session helper functions for CloudOS.

Functions

build_resume_payload([instance_type, ...])	Build the resume session payload for the API.
build_session_payload(name, backend, project_id)	Build the complex session creation payload for the API.
confirm_session_stop(session_data[, ...])	Display session termination confirmation details.
create_interactive_session_list_table(sessions)	Create a rich table displaying interactive sessions with interactive pagination.
export_session_status_csv(session_data[, ...])	Export session status as CSV.
export_session_status_json(session_data[, ...])	Export session status as JSON.
fetch_interactive_session_page(cl, ...)	Helper function to fetch a specific page of interactive sessions.
format_cost([cost_value])	Format cost as currency.
format_duration(seconds)	Convert seconds to human-readable format.
format_instance_type(instance_type[, ...])	Format instance type with spot indicator.
format_session_creation_table(session_data)	Display session creation result in table format.
format_session_status_table(session_data[, ...])	Wrapper function to display session status as a rich table.
format_stop_success_output(session_data[, wait])	Display successful session stop output.
format_timestamp([iso_timestamp])	Convert ISO8601 timestamp to readable format.
get_interactive_session_status(cloudos_url, ...)	Wrapper function to fetch session status from API.
map_status(api_status)	Map API status value to user-friendly display status.
parse_data_file(data_file_str)	Parse data file format: either S3 or CloudOS dataset path.
parse_link_path(link_path_str)	Parse link path format: supports S3, CloudOS, or legacy colon format.
parse_shutdown_duration(duration_str)	Parse shutdown duration string to ISO8601 datetime string.
parse_watch_timeout_duration(duration_str)	Parse watch timeout duration string to seconds.
poll_session_termination(cloudos_url, ...[, ...])	Poll session status until it reaches a terminal state.
process_interactive_session_list(sessions[, ...])	Process interactive sessions data into a pandas DataFrame.
resolve_data_file_id(datasets_api, dataset_path)	Resolve nested dataset path to actual file ID.
save_interactive_session_list_to_csv(df, outfile)	Save interactive session list to CSV file.
transform_session_response(api_response)	Transform raw API response to user-friendly display format.
validate_instance_type(instance_type[, ...])	Validate instance type format for the given execution platform.
validate_session_id(session_id)	Validate session ID format (24-character hex string).

Classes

InteractiveSessionAPI(cloudos_url, apikey[, ...])	API client for interactive session operations.
OutputFormatter()	Handles formatting output in different formats.
WatchModeManager(api_client, session_id, team_id)	Manages watch mode polling and display.

class cloudos_cli.interactive_session.interactive_session.InteractiveSessionAPI(cloudos_url, apikey, verify_ssl=True)

Bases: object

API client for interactive session operations.

Parameters:

• cloudos_url (str)

• apikey (str)

• verify_ssl (bool)

REQUEST_TIMEOUT = 30

get_session_status(session_id, team_id)

Retrieve session status from API endpoint.

GET /api/v2/interactive-sessions/{sessionId}?teamId={teamId}

Parameters:

• session_id (str) – Session ID (24-character hex)

• team_id (str) – Team/workspace ID

Returns:

Session status response

Return type:

dict

Raises:

• PermissionError – If authentication fails (401, 403)

• ValueError – If session not found (404)

• RuntimeError – For other API errors

class cloudos_cli.interactive_session.interactive_session.OutputFormatter

Bases: object

Handles formatting output in different formats.

static format_csv(session_data)

Export as CSV with key fields.

Parameters:

session_data (dict)

Return type:

str

static format_json(raw_response)

Return raw API response as formatted JSON.

Parameters:

raw_response (dict)

Return type:

str

static format_stdout(session_data, cloudos_url)

Display session status as a rich table with color coding.

Parameters:

• session_data (dict)

• cloudos_url (str)

Return type:

None

class cloudos_cli.interactive_session.interactive_session.WatchModeManager(api_client, session_id, team_id, interval=10)

Bases: object

Manages watch mode polling and display.

Parameters:

• api_client (InteractiveSessionAPI)

• session_id (str)

• team_id (str)

• interval (int)

get_elapsed_time()

Get formatted elapsed time.

Return type:

str

watch(verbose=False)

Continuously poll session status until reaching terminal state.

Terminal states: running, paused, terminated

Handles Ctrl+C gracefully.

Parameters:

verbose (bool)

Return type:

dict

cloudos_cli.interactive_session.interactive_session.build_resume_payload(instance_type=None, storage_size=None, cost_limit=None, shutdown_at=None, data_files=None, s3_mounts=None)

Build the resume session payload for the API.

Only includes fields that have been specified (all are optional).

Parameters:

• instance_type (str, optional) – New instance type (if changing)

• storage_size (int, optional) – New storage size in GB (if changing)

• cost_limit (float, optional) – New compute cost limit (if changing)

• shutdown_at (str, optional) – New auto-shutdown datetime in ISO8601 format (if changing)

• data_files (list, optional) – Additional data files to mount

• s3_mounts (list, optional) – Additional S3 mounts (AWS only)

Returns:

Resume payload for API request

Return type:

dict

cloudos_cli.interactive_session.interactive_session.build_session_payload(name, backend, project_id, execution_platform='aws', instance_type='c5.xlarge', storage_size=500, is_spot=False, is_shared=False, cost_limit=-1, shutdown_at=None, data_files=None, s3_mounts=None, r_version=None, spark_master_type=None, spark_core_type=None, spark_workers=1)

Build the complex session creation payload for the API.

Parameters:

• name (str) – Session name (1-100 characters)

• backend (str) – Backend type: regular, vscode, spark, rstudio

• project_id (str) – Project MongoDB ObjectId

• execution_platform (str, optional) – Execution platform: ‘aws’ (default) or ‘azure’

• instance_type (str) – Instance type (EC2 for AWS, e.g., c5.xlarge; Azure VM size, e.g., Standard_F1s)

• storage_size (int) – Storage in GB (default: 500, range: 100-5000)

• is_spot (bool) – Use spot instances (AWS only, default: False)

• is_shared (bool) – Make session shared (default: False)

• cost_limit (float) – Compute cost limit in USD (default: -1 for unlimited)

• shutdown_at (str) – ISO8601 datetime for auto-shutdown (optional)

• data_files (list) – List of data file dicts. For AWS: CloudOS or S3. For Azure: CloudOS only.

• s3_mounts (list) – List of S3 mount dicts (AWS only, ignored for Azure)

• r_version (str) – R version for RStudio (required for rstudio backend)

• spark_master_type (str) – Spark master instance type (required for spark backend, AWS only)

• spark_core_type (str) – Spark core instance type (required for spark backend, AWS only)

• spark_workers (int) – Initial number of Spark workers (default: 1, AWS only)

Returns:

Complete payload for API request

Return type:

dict

cloudos_cli.interactive_session.interactive_session.confirm_session_stop(session_data, no_upload=False, force=False)

Display session termination confirmation details.

Parameters:

• session_data (dict) – Session data from API response

• no_upload (bool) – Whether data upload on close is disabled

• force (bool) – Whether force abort is enabled

Return type:

None

cloudos_cli.interactive_session.interactive_session.create_interactive_session_list_table(sessions, pagination_metadata=None, selected_columns=None, page_size=10, fetch_page_callback=None)

Create a rich table displaying interactive sessions with interactive pagination.

Parameters:

• sessions (list) – List of session objects from the API

• pagination_metadata (dict, optional) – Pagination information from the API response

• selected_columns (str or list, optional) – Comma-separated string or list of column names to display. If None, uses responsive column selection based on terminal width. Available columns: id, name, status, type, instance, cost, owner

• page_size (int, optional) – Number of sessions per page for interactive pagination. Default=10.

• fetch_page_callback (callable, optional) – Callback function to fetch a specific page of results. Should accept page number (1-indexed) and return dict with ‘sessions’ and ‘pagination_metadata’ keys.

cloudos_cli.interactive_session.interactive_session.export_session_status_csv(session_data, output_file=None)

Export session status as CSV.

Parameters:

• session_data (dict) – Transformed session data (from transform_session_response)

• output_file (str, optional) – Path to save CSV file. If None, returns CSV string.

Returns:

CSV formatted string

Return type:

str

cloudos_cli.interactive_session.interactive_session.export_session_status_json(session_data, output_file=None)

Export session status as JSON.

Parameters:

• session_data (dict) – Raw API response

• output_file (str, optional) – Path to save JSON file. If None, returns JSON string.

Returns:

JSON formatted string

Return type:

str

cloudos_cli.interactive_session.interactive_session.fetch_interactive_session_page(cl, workspace_id, page_num, limit, filter_status, filter_only_mine, archived, verify_ssl)

Helper function to fetch a specific page of interactive sessions.

Parameters:

• cl (Cloudos) – CloudOS API client instance

• workspace_id (str) – Workspace ID

• page_num (int) – Page number to fetch

• limit (int) – Number of results per page

• filter_status (tuple or None) – Status filters

• filter_only_mine (bool) – Whether to filter only user’s sessions

• archived (bool) – Whether to include archived sessions

• verify_ssl (bool or str) – SSL verification setting

Returns:

API response with sessions and pagination metadata

Return type:

dict

cloudos_cli.interactive_session.interactive_session.format_cost(cost_value=None)

Format cost as currency.

Examples: “$12.50”, “$0.00”

Parameters:

cost_value (float)

Return type:

str

cloudos_cli.interactive_session.interactive_session.format_duration(seconds)

Convert seconds to human-readable format.

Examples: “2h 15m”, “45m 30s”, “30s”

Parameters:

seconds (int)

Return type:

str

cloudos_cli.interactive_session.interactive_session.format_instance_type(instance_type, is_cost_saving=False)

Format instance type with spot indicator.

Examples: “c5.xlarge”, “c5.xlarge (spot)”

Parameters:

• instance_type (str)

• is_cost_saving (bool)

Return type:

str

cloudos_cli.interactive_session.interactive_session.format_session_creation_table(session_data, instance_type=None, storage_size=None, backend_type=None, r_version=None, spark_master=None, spark_core=None, spark_workers=None, data_files=None, s3_mounts=None)

Display session creation result in table format.

Parameters:

• session_data (dict) – Session data from API response

• instance_type (str, optional) – Instance type that was requested (for display if not in response)

• storage_size (int, optional) – Storage size that was requested (for display if not in response)

• backend_type (str, optional) – Backend type (regular, vscode, spark, rstudio) for backend-specific display

• r_version (str, optional) – R version for RStudio backend

• spark_master (str, optional) – Spark master instance type

• spark_core (str, optional) – Spark core instance type

• spark_workers (int, optional) – Number of Spark workers

• data_files (list, optional) – List of parsed data file objects to display

• s3_mounts (list, optional) – List of parsed S3 mount objects to display

Returns:

Formatted table output

Return type:

str

cloudos_cli.interactive_session.interactive_session.format_session_status_table(session_data, cloudos_url=None)

Wrapper function to display session status as a rich table.

Parameters:

• session_data (dict) – Transformed session data (from transform_session_response)

• cloudos_url (str, optional) – CloudOS URL for creating links

Return type:

None

cloudos_cli.interactive_session.interactive_session.format_stop_success_output(session_data, wait=False)

Display successful session stop output.

Parameters:

• session_data (dict) – Final session data from API response

• wait (bool) – Whether the command waited for full termination

Return type:

None

cloudos_cli.interactive_session.interactive_session.format_timestamp(iso_timestamp=None)

Convert ISO8601 timestamp to readable format.

Example: “2026-03-13 10:30:00”

Parameters:

iso_timestamp (str)

Return type:

str

cloudos_cli.interactive_session.interactive_session.get_interactive_session_status(cloudos_url, apikey, session_id, team_id, verify_ssl=True, verbose=False)

Wrapper function to fetch session status from API.

Parameters:

• cloudos_url (str) – CloudOS platform URL

• apikey (str) – API key for authentication

• session_id (str) – Session ID (24-char hex)

• team_id (str) – Team/workspace ID

• verify_ssl (bool) – Whether to verify SSL certificates

• verbose (bool) – Whether to print verbose output

Returns:

Raw API response

Return type:

dict

Raises:

• ValueError – If session not found

• PermissionError – If authentication fails

• RuntimeError – For other API errors

cloudos_cli.interactive_session.interactive_session.map_status(api_status)

Map API status value to user-friendly display status.

Converts API status values (like ‘ready’, ‘aborted’) to display values (like ‘running’, ‘paused’) matching the list command.

Parameters:

api_status (str)

Return type:

str

cloudos_cli.interactive_session.interactive_session.parse_data_file(data_file_str)

Parse data file format: either S3 or CloudOS dataset path.

Supports mounting both S3 files and CloudOS dataset files into the session.

Parameters:

data_file_str (str) –

Format: - S3 file: s3://bucket_name/path/to/file.txt - CloudOS dataset: project_name/dataset_path or project_name > dataset_path

Examples: - s3://lifebit-featured-datasets/pipelines/phewas/data.csv - leila-test/Data/3_vcf_list.txt

Returns:

Parsed data item. For S3: {“type”: “s3”, “s3_bucket”: “…”, “s3_prefix”: “…”}

For CloudOS dataset: {“type”: “cloudos”, “project_name”: “…”, “dataset_path”: “…”}

Return type:

dict

Raises:

ValueError – If format is invalid

cloudos_cli.interactive_session.interactive_session.parse_link_path(link_path_str)

Parse link path format: supports S3, CloudOS, or legacy colon format.

Links an S3 folder or CloudOS folder to the session for read/write access.

Parameters:

link_path_str (str) – Format (one of): - S3 path: s3://bucketName/s3Prefix (e.g., s3://my-bucket/data/) - CloudOS folder: project/folder_path (e.g., leila-test/Data) - Legacy format (deprecated): mountName:bucketName:s3Prefix

Returns:

Tuple of (type, data) where type is ‘s3’ or ‘cloudos’ and data contains: For S3: {“s3_bucket”: “…”, “s3_prefix”: “…”} For CloudOS: {“project_name”: “…”, “folder_path”: “…”}

Return type:

dict

cloudos_cli.interactive_session.interactive_session.parse_shutdown_duration(duration_str)

Parse shutdown duration string to ISO8601 datetime string.

Accepts formats: 30m, 2h, 8h, 1d, 2d

Parameters:

duration_str (str) – Duration string (e.g., “2h”, “30m”, “1d”)

Returns:

ISO8601 formatted datetime string (future time)

Return type:

str

cloudos_cli.interactive_session.interactive_session.parse_watch_timeout_duration(duration_str)

Parse watch timeout duration string to seconds.

Accepts formats: 30m, 2h, 1d, 30s

Parameters:

duration_str (str) – Duration string (e.g., “30m”, “2h”, “1d”, “30s”)

Returns:

Duration in seconds

Return type:

int

cloudos_cli.interactive_session.interactive_session.poll_session_termination(cloudos_url, apikey, session_id, team_id, max_wait=300, poll_interval=5, verify_ssl=True)

Poll session status until it reaches a terminal state.

Parameters:

• cloudos_url (str) – CloudOS API URL

• apikey (str) – API key for authentication

• session_id (str) – Session ID to monitor

• team_id (str) – Team/workspace ID

• max_wait (int) – Maximum time to wait in seconds (default: 300 = 5 minutes)

• poll_interval (int) – Polling interval in seconds (default: 5)

• verify_ssl (bool) – Whether to verify SSL certificates

Returns:

Final session status response

Return type:

dict

Raises:

TimeoutError – If session doesn’t reach terminal state within max_wait

cloudos_cli.interactive_session.interactive_session.process_interactive_session_list(sessions, all_fields=False)

Process interactive sessions data into a pandas DataFrame.

Parameters:

• sessions (list) – List of session objects from the API

• all_fields (bool, default=False) – If True, include all fields from the API response. If False, include only the most relevant fields.

Returns:

df – DataFrame with session data

Return type:

pandas.DataFrame

cloudos_cli.interactive_session.interactive_session.resolve_data_file_id(datasets_api, dataset_path)

Resolve nested dataset path to actual file ID.

Searches across all datasets in the project to find the target file. This allows paths like ‘Data/file.txt’ to work even if ‘Data’ is a folder within a dataset (not a dataset name itself).

Parameters:

• datasets_api (Datasets) – Initialized Datasets API instance (with correct project_name)

• dataset_path (str) – Nested path to file within the project (e.g., ‘Data/file.txt’ or ‘Folder/subfolder/file.txt’) Can start with a dataset name or a folder name within any dataset.

Returns:

Data item object with resolved file ID: {“kind”: “File”, “item”: “<fileId>”, “name”: “<fileName>”}

Return type:

dict

Raises:

ValueError – If file not found in any dataset/folder

cloudos_cli.interactive_session.interactive_session.save_interactive_session_list_to_csv(df, outfile, count=None)

Save interactive session list to CSV file.

Parameters:

• df (pandas.DataFrame) – The session data to save

• outfile (str) – Path to the output CSV file

• count (int, optional) – Total number of sessions on this page for display message

cloudos_cli.interactive_session.interactive_session.transform_session_response(api_response)

Transform raw API response to user-friendly display format.

Parameters:

api_response (dict)

Return type:

dict

cloudos_cli.interactive_session.interactive_session.validate_instance_type(instance_type, execution_platform='aws')

Validate instance type format for the given execution platform.

Parameters:

• instance_type (str) – Instance type to validate

• execution_platform (str) – ‘aws’ or ‘azure’

Returns:

(is_valid: bool, error_message: str or None)

Return type:

tuple

cloudos_cli.interactive_session.interactive_session.validate_session_id(session_id)

Validate session ID format (24-character hex string).

Parameters:

session_id (str)

Return type:

bool