cloudos-cb-py 1.2.0__tar.gz

cloudos_cb_py-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lifebit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cloudos_cb_py-1.2.0/PKG-INFO

@@ -0,0 +1,400 @@
+Metadata-Version: 2.4
+Name: cloudos-cb-py
+Version: 1.2.0
+Summary: Python client for CloudOS Cohort Browser API
+Author-email: David Pineyro <david.pineyro@lifebit.ai>
+License: MIT License
+        
+        Copyright (c) 2026 Lifebit
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/lifebit-ai/cloudos-cb-py
+Project-URL: Repository, https://github.com/lifebit-ai/cloudos-cb-py
+Project-URL: Issues, https://github.com/lifebit-ai/cloudos-cb-py/issues
+Project-URL: Changelog, https://github.com/lifebit-ai/cloudos-cb-py/blob/main/CHANGELOG.md
+Keywords: cloudos,cohort-browser,api-client,bioinformatics
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pandas>=1.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Dynamic: license-file
+
+# cloudos-cb-py
+
+Python client for the CloudOS Cohort Browser API. Provides functions for schema discovery,
+table exploration, and SQL query execution with team-based access control.
+
+## Requirements
+
+- Python >= 3.9
+- requests >= 2.28.0
+- pandas >= 1.5.0
+
+## Prerequisites
+
+**IMPORTANT:** Before using this package, ensure the following requirements are met:
+
+- **Bastion must be enabled** for your workspace
+- **You are running the package from within an interactive session**
+- **The interactive session and the cohort queried must be in the same workspace**
+
+Without these prerequisites, API calls will fail even with valid credentials.
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install cloudos-cb-py
+```
+
+### From source
+
+```bash
+git clone https://github.com/lifebit-ai/cloudos-cb-py
+cd cloudos-cb-py
+pip install .
+```
+
+### Development install (includes test dependencies)
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### 1. Configure a profile
+
+```python
+import cloudos_cb
+
+cloudos_cb.configure(
+    profilename="production",
+    apikey="your-api-key-here",
+    workspace_id="953h453uhr73894hhr9348h9",
+    set_default=True,
+)
+```
+
+Credentials are stored in `~/.cloudos-cb/config.json` with 0600 permissions.
+Set `CLOUDOS_CONFIG_DIR` to store the file elsewhere.
+
+### 2. List configured profiles
+
+```python
+profiles = cloudos_cb.profile_list()
+print(profiles)
+# Returns a pandas DataFrame with columns:
+# profile_name, workspace_id, base_url, default, created_at, updated_at
+```
+
+### 3. Discover cohort tables
+
+```python
+tables = cloudos_cb.cohort_tables(cohort_id="1a2b3c4d5e6f7g8h9i10j11k")
+print(tables)
+# Cohort 1a2b3c4d5e6f7g8h9i10j11k:
+#   - omop_data.person
+#       - person_id (integer)
+#       - year_of_birth (integer)
+#       - gender_concept_id (integer)
+#       ...
+#   - omop_data.observation
+#       ...
+#
+# Total: 1 database(s), 5 table(s)
+
+# Access raw data
+schema_list = tables.schemas
+```
+
+### 4. Validate SQL (optional but recommended)
+
+```python
+result = cloudos_cb.sql_validate(
+    sql="SELECT person_id FROM omop_data.person WHERE year_of_birth >= 1960"
+)
+
+if result["isValid"]:
+    print("SQL is valid")
+else:
+    print("SQL invalid:", result["error"]["message"])
+```
+
+### 5. Execute a query (high-level)
+
+```python
+df = cloudos_cb.query(
+    cohort_id="1a2b3c4d5e6f7g8h9i10j11k",
+    sql="SELECT person_id, gender_concept_id FROM omop_data.person LIMIT 100",
+)
+print(df.head())
+print(f"Total rows: {df.attrs['total_rows']}")
+```
+
+By default `query()` fetches all pages automatically. To return only the first page:
+
+```python
+df = cloudos_cb.query(
+    cohort_id="1a2b3c4d5e6f7g8h9i10j11k",
+    sql="SELECT person_id FROM omop_data.person",
+    all_pages=False,
+    page_size=500,
+)
+```
+
+### 6. Manual workflow
+
+For fine-grained control over the submit / poll / fetch cycle:
+
+```python
+# Step 1: Submit
+task = cloudos_cb.query_submit_async(
+    cohort_id="1a2b3c4d5e6f7g8h9i10j11k",
+    sql="SELECT person_id FROM omop_data.person",
+    pagination={"pageNumber": 0, "pageSize": 100},
+)
+print("Task ID:", task["task_id"])
+
+# Step 2: Poll
+status = cloudos_cb.query_status(task_id=task["task_id"])
+print("Status:", status["status"])
+# status["status"] is one of: "pending", "running", "completed", "failed"
+
+# Step 3: Fetch results when completed
+df = cloudos_cb.query_results(task_id=task["task_id"])
+print(df)
+```
+
+## API Reference
+
+### `configure(profilename, apikey, workspace_id, base_url=..., set_default=False)`
+
+Create or update a named credential profile.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `profilename` | str | Profile name (required) |
+| `apikey` | str | API key (required) |
+| `workspace_id` | str | Workspace/team ID (required) |
+| `base_url` | str | CloudOS base URL (default: `https://cloudos.lifebit.ai`) |
+| `set_default` | bool | Mark this profile as the default |
+
+---
+
+### `profile_list()`
+
+Return a `pandas.DataFrame` of all configured profiles.
+
+---
+
+### `cohort_tables(cohort_id, profilename="")`
+
+Retrieve schemas, tables, and columns for a cohort.
+
+Returns a `CohortTables` object. Print it for a human-readable tree, or
+access `.schemas` for the raw list.
+
+---
+
+### `sql_validate(sql, profilename="")`
+
+Validate SQL syntax and references before execution.
+
+Returns a `dict` with `isValid` (bool), `tableReferences`, `columnReferences`,
+and on failure an `error` dict with a `message` key.
+
+---
+
+### `query_submit_async(cohort_id, sql, pagination=None, profilename="")`
+
+Submit an async SQL task. Returns a `dict` with:
+
+| Key | Description |
+|-----|-------------|
+| `task_id` | Use this to poll status and fetch results |
+| `status` | Initial status (typically `"pending"`) |
+| `query` | Echo of the submitted SQL |
+| `type` | Task type string |
+| `sync_execution_timeout` | Server-side timeout hint in ms |
+| `full_response` | Raw API response |
+
+`pagination` is an optional `dict` with `pageNumber` (int >= 0) and
+`pageSize` (int >= 1).
+
+---
+
+### `query_status(task_id, profilename="")`
+
+Check task status. Returns a `dict` with `task_id`, `status`, `type`,
+`count_of_results`, `query`, `created_at`, `started_at`, `ended_at`,
+`user`, `full_response`.
+
+---
+
+### `query_results(task_id, profilename="")`
+
+Fetch results for a completed task. Returns a `pandas.DataFrame` with
+metadata in `.attrs`:
+
+| Attribute | Description |
+|-----------|-------------|
+| `total_rows` | Total rows across all pages |
+| `page` | Page index returned |
+| `page_size` | Rows in this page |
+| `total_pages` | Total number of pages available |
+
+---
+
+### `query(cohort_id, sql, poll_interval=2, max_wait=600, page_size=1000, all_pages=True, profilename="")`
+
+High-level orchestrator. Submits, polls, and fetches results automatically.
+When `all_pages=True`, submits one async task per page and concatenates them.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `poll_interval` | 2 | Seconds between status checks (minimum 1) |
+| `max_wait` | 600 | Maximum seconds to wait per task |
+| `page_size` | 1000 | Rows per page |
+| `all_pages` | True | Fetch all pages and combine them |
+
+---
+
+## Using multiple profiles
+
+```python
+# Configure multiple profiles
+cloudos_cb.configure(
+    profilename="production",
+    apikey="prod-key",
+    workspace_id="prod-workspace",
+    set_default=True,
+)
+cloudos_cb.configure(
+    profilename="staging",
+    apikey="stage-key",
+    workspace_id="stage-workspace",
+)
+
+# Use default profile (production)
+df = cloudos_cb.query(cohort_id="cohort-prod", sql="SELECT 1")
+
+# Explicitly use staging profile
+df = cloudos_cb.query(
+    cohort_id="cohort-stage",
+    sql="SELECT 1",
+    profilename="staging",
+)
+```
+
+## Configuration storage
+
+The config file is located at:
+- `$CLOUDOS_CONFIG_DIR/config.json` when the env var is set
+- `~/.cloudos/config.json` otherwise (home directory)
+
+File permissions are set to 0600 (user read/write only). The default location
+(`~/.cloudos/`) is outside any repository. If you override `CLOUDOS_CONFIG_DIR`
+to a path inside a project, add that directory to your `.gitignore`.
+
+## Error handling
+
+```python
+from cloudos_cb import (
+    CloudOSAuthError,
+    CloudOSAccessError,
+    CloudOSServerError,
+    CloudOSConfigError,
+    CloudOSValidationError,
+)
+
+try:
+    df = cloudos_cb.query(cohort_id="...", sql="SELECT 1")
+except CloudOSAuthError:
+    print("Authentication failed - check your API key.")
+except CloudOSAccessError:
+    print("Access denied or resource not found.")
+except CloudOSServerError:
+    print("Server error - try again later.")
+except CloudOSConfigError:
+    print("Profile not configured - run configure() first.")
+except CloudOSValidationError as e:
+    print(f"Invalid input: {e}")
+```
+
+## Logging
+
+The package uses Python's standard `logging` module under the `cloudos_cb`
+namespace. To see informational messages:
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)
+```
+
+## Running tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+To check code style:
+
+```bash
+flake8 cloudos_cb tests
+```
+
+## Package structure
+
+```
+cloudos-cb-py/
+├── pyproject.toml        # Package metadata and build config
+├── CHANGELOG.md
+├── README.md
+├── LICENSE
+├── cloudos_cb/           # Package source
+│   ├── __init__.py       # Public API
+│   ├── exceptions.py     # Custom exception classes
+│   ├── config.py         # Profile management
+│   ├── http.py           # Authenticated HTTP helpers
+│   ├── utils.py          # Shared utilities
+│   └── queries.py        # Cohort Browser query functions
+└── tests/
+    ├── test_config.py
+    ├── test_http.py
+    ├── test_utils.py
+    └── test_query.py
+```