# Runapy
Python client for the [Run:ai REST API](https://app.run.ai/api/docs).
- A single class interface to perform all Run:ai REST API actions
- Automatic API token refresh, useful for long-running tasks
- Built-in retry mechanism for handling transient network errors
- Runtime data validation and serialization using Pydantic models
```python
from runai.configuration import Configuration
from runai.api_client import ApiClient
from runai.runai_client import RunaiClient
config = Configuration(
client_id="your-client-id",
client_secret="your-client-secret",
runai_base_url="https://your-org.run.ai",
)
client = RunaiClient(ApiClient(config))
# Start making API calls
projects = client.organizations.projects.get_projects()
```
Jump to our [examples](examples/) section for more detailed examples.
## Table of Contents
1. [Requirements](#requirements)
2. [Installation](#installation)
3. [Getting Started](#getting-started)
4. [API Structure](#api-structure)
5. [Client Configuration Options](#client-configuration-options)
6. [Authentication Methods](#authentication-methods)
7. [Examples](#examples)
8. [Versioning](#versioning)
9. [About](#about)
10. [License](#license)
## Requirements
* **Run:ai control-plane version >= 2.18:** The client requires Run:ai control-plane version 2.18 or higher
* **Python version >= 3.8:** Required for compatibility with core dependencies
* **Run:ai Client Application:** Required to generate the `client_id` and `client_secret` credentials. [Create a client application](https://docs.run.ai/latest/developer/rest-auth/#create-a-client-application)
#### Note on Token Permissions
Ensure your application token has the required role and scope permissions for your intended API operations. \
API calls will fail with a 403 error if the token lacks sufficient role or scope.
## Installation
For SaaS environments or latest Run:ai control-plane:
```bash
pip3 install runapy
```
For self-hosted environments, specify the minor version matching your control-plane version. \
For example, with Run:ai 2.19 control-plane:
```bash
pip3 install runapy~=1.219.0
```
To understand the versioning scheme, refer to the [Versioning](#versioning) section.
## Getting Started
The client provides three client types to suit different use cases:
1. `ApiClient`: Standard synchronous client for sequential operations
2. `ThreadedApiClient`: Thread-safe client for parallel operations in multithreaded environments
3. `AsyncApiClient`: Asynchronous client for `async/await` support
Here's a basic example using the standard client:
```python
from runai.configuration import Configuration
from runai.api_client import ApiClient
from runai.runai_client import RunaiClient
config = Configuration(
client_id="your-client-id",
client_secret="your-client-secret",
runai_base_url="https://your-org.run.ai",
)
client = RunaiClient(ApiClient(config))
# Start making API calls
projects = client.organizations.projects.get_projects()
```
See all client configuration options in the [Client configuration options](#client-configuration-options)
See [Examples](#examples) for quickstart guides
### Multithreaded Operations
For parallel operations in a multithreaded environment, use `ThreadedApiClient`:
```python
from runai.api_client import ThreadedApiClient
with RunaiClient(ThreadedApiClient(config)) as client:
# These operations can run concurrently
projects = client.organizations.projects.get_projects()
```
### Asynchronous Operations
For async/await support, use `AsyncApiClient`:
```python
import asyncio
from runai.api_client import AsyncApiClient
async def main():
async with RunaiClient(AsyncApiClient(config)) as client:
projects = await client.organizations.projects.get_projects()
asyncio.run(main())
```
## API Structure
The client matches the Run:ai REST API documentation structure with three levels of groups:
1. **API Categories**: Top-level groupings (e.g., `organizations`, `authentication_and_authorization`)
2. **API Groups**: Resource-specific groups within categories (e.g., `projects`, `departments` under `organizations`)
3. **API Methods**: Individual operations on resources (e.g., `get_projects`, `create_project`)
Example of navigating the API structure:
```python
# List available API groups in the organizations category
client.organizations.options()
# ['projects', 'departments', 'clusters', 'nodes', ...]
# List available methods in the projects group
client.organizations.projects.options()
# ['get_projects', 'create_project', 'delete_project', ...]
```
### Deprecated Methods
Deprecated methods are hidden by default. \
To view both supported and deprecated methods, use the `include_deprecated` flag:
```python
client.organizations.projects.options(include_deprecated=True)
```
## Client Configuration Options
| Parameter | Type | Description |
| :-------- | :------- | :-------------------------------- |
| `client_id` | `string` | **Required**: The Run:ai application client ID, usually representing the application name |
| `client_secret` | `string` | **Required**: The client secret associated with the Run:ai application |
| `runai_base_url` | `string` | **Required**: The base URL for the Run:ai instance your organization uses (e.g., `https://myorg.run.ai`) |
| `bearer_token` | `string` | **Optional**: Bearer token for CLIv2 compatibility. Cannot be used together with client credentials |
| `verify_ssl` | `bool` | **Optional**: Whether to verify SSL certificates. Default is `True` |
| `ssl_ca_cert` | `string` | **Optional**: Path to CA certificate file |
| `cert_file` | `string` | **Optional**: Path to client certificate file |
| `key_file` | `string` | **Optional**: Path to client key file |
| `pool_maxsize` | `int` | **Optional**: Maximum number of connections to keep in pool. Default is `4` |
| `pool_size` | `int` | **Optional**: Initial number of connections in pool. Defaults to `pool_maxsize` |
| `retry_enabled` | `bool` | **Optional**: Whether to enable request retries. Default is `True` |
| `retry_max_retries` | `int` | **Optional**: Maximum number of retry attempts. Default is `3` |
| `retry_backoff_factor` | `float` | **Optional**: Exponential backoff factor between retries. Default is `0.5` |
| `proxy_url` | `string` | **Optional**: URL for proxy server |
| `proxy_headers` | `dict` | **Optional**: Additional headers for proxy |
| `proxy_server_name` | `string` | **Optional**: SNI hostname for TLS connections |
| `auto_refresh_token` | `bool` | **Optional**: Whether to auto refresh token before expiry. Default is `True` |
| `token_refresh_margin` | `int` | **Optional**: Seconds before expiry to refresh token. Default is `60` |
| `debug` | `bool` | **Optional**: Enable debug logging. Default is `False` |
## Authentication Methods
The client supports three authentication methods:
### 1. Client Credentials
Use client ID and secret from your Run:ai application:
```python
config = Configuration(
client_id="your-client-id",
client_secret="your-client-secret",
runai_base_url="https://your-org.run.ai"
)
```
### 2. Bearer Token
Direct authentication using a bearer token:
```python
config = Configuration(
bearer_token="your-bearer-token",
runai_base_url="https://your-org.run.ai"
)
```
### 3. CLIv2 Token (Bearer token)
The CLIv2 token method is useful for:
* Local development and testing
* Scripts running on machines with existing CLI authentication
* Maintaining consistent authentication with CLI sessions
* End user operations
Requirements:
* Run:ai CLI v2 installed
* Successful `runai login` completed
* Valid authentication token in CLI config
```python
from runai.cliv2_config_loader import CLIv2Config
# Default config path is ~/.runai
config = CLIv2Config()
# Or specify a custom path
config = CLIv2Config(cliv2_config_path="/path/to/.runai")
token = config.token
runai_base_url = config.control_plane_url
cluster_id = config.cluster_uuid
client = RunaiClient(
cluster_id=cluster_id,
bearer_token=token,
runai_base_url=runai_base_url
)
```
## Examples
The repo provides Hand-crafted examples showing common use cases.\
See [here](examples/).
The API client include APIs for all Run:ai UI functionalities.\
We encourage you to explore the client relevant categories if you attempt to run a task that is not shown in the examples.
Note: There are also auto-generated examples under /examples/generated (may require syntax adjustments to run properly)
## Versioning
The Run:ai API is an integral part of the control-plane microservices.\
As the control-plane evolves, APIs may be added, modified, or deprecated.\
This version binding ensures that API changes in the client match the control-plane capabilities.
The client follows semantic versioning (X.Y.Z) with a special alignment to Run:ai's control-plane versions:
* **X (Major)**: Major changes in the client
* **Y (Minor)**: Run:ai control-plane version (e.g., 219 for control-plane 2.19)
* **Z (Patch)**: Small bug fixes and non-breaking changes
For example:
```
1.218.0 # Initial release for control-plane 2.18
1.218.1 # Patch release for control-plane 2.18
1.219.0 # Initial release for control-plane 2.19
```
This versioning convention ensures that:
1. Each control-plane version has a matching client version
2. Client versions clearly indicate their compatible control-plane version
3. Client breaking changes are managed in major version bumps
## About
This package is an open-source project maintained by the Run:ai Professional Services team.\
If you experience any issues or have feature requests, please submit them via the [repository’s issue tracker](https://github.com/runai-professional-services/runapy/issues).
## License
This project is licensed under the Apache-2 License. \
See the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/runai-professional-services/runapy",
"name": "runapy",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "runai, kubernetes, gpu, orchestration",
"author": "Run:ai Professional Services Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/61/ca/a6b2bb563d53ced4b1b99008dc2f5e7f1a97cee89bbcf96c86d0e23946bb/runapy-1.222.0.tar.gz",
"platform": null,
"description": "# Runapy\n\nPython client for the [Run:ai REST API](https://app.run.ai/api/docs).\n\n- A single class interface to perform all Run:ai REST API actions\n- Automatic API token refresh, useful for long-running tasks\n- Built-in retry mechanism for handling transient network errors\n- Runtime data validation and serialization using Pydantic models\n\n```python\nfrom runai.configuration import Configuration\nfrom runai.api_client import ApiClient\nfrom runai.runai_client import RunaiClient\n\nconfig = Configuration(\n client_id=\"your-client-id\",\n client_secret=\"your-client-secret\",\n runai_base_url=\"https://your-org.run.ai\",\n)\n\nclient = RunaiClient(ApiClient(config))\n\n# Start making API calls\nprojects = client.organizations.projects.get_projects()\n```\n\nJump to our [examples](examples/) section for more detailed examples.\n\n## Table of Contents\n\n1. [Requirements](#requirements)\n2. [Installation](#installation)\n3. [Getting Started](#getting-started)\n4. [API Structure](#api-structure)\n5. [Client Configuration Options](#client-configuration-options)\n6. [Authentication Methods](#authentication-methods)\n7. [Examples](#examples)\n8. [Versioning](#versioning)\n9. [About](#about)\n10. [License](#license)\n\n## Requirements\n* **Run:ai control-plane version >= 2.18:** The client requires Run:ai control-plane version 2.18 or higher\n* **Python version >= 3.8:** Required for compatibility with core dependencies\n* **Run:ai Client Application:** Required to generate the `client_id` and `client_secret` credentials. [Create a client application](https://docs.run.ai/latest/developer/rest-auth/#create-a-client-application)\n\n#### Note on Token Permissions\nEnsure your application token has the required role and scope permissions for your intended API operations. \\\nAPI calls will fail with a 403 error if the token lacks sufficient role or scope.\n\n## Installation\n\nFor SaaS environments or latest Run:ai control-plane:\n```bash\npip3 install runapy\n```\n\nFor self-hosted environments, specify the minor version matching your control-plane version. \\\nFor example, with Run:ai 2.19 control-plane:\n```bash\npip3 install runapy~=1.219.0\n```\nTo understand the versioning scheme, refer to the [Versioning](#versioning) section.\n\n## Getting Started\n\nThe client provides three client types to suit different use cases:\n\n1. `ApiClient`: Standard synchronous client for sequential operations\n2. `ThreadedApiClient`: Thread-safe client for parallel operations in multithreaded environments\n3. `AsyncApiClient`: Asynchronous client for `async/await` support\n\nHere's a basic example using the standard client:\n\n```python\nfrom runai.configuration import Configuration\nfrom runai.api_client import ApiClient\nfrom runai.runai_client import RunaiClient\n\nconfig = Configuration(\n client_id=\"your-client-id\",\n client_secret=\"your-client-secret\",\n runai_base_url=\"https://your-org.run.ai\",\n)\n\nclient = RunaiClient(ApiClient(config))\n\n# Start making API calls\nprojects = client.organizations.projects.get_projects()\n```\nSee all client configuration options in the [Client configuration options](#client-configuration-options)\n\nSee [Examples](#examples) for quickstart guides\n\n### Multithreaded Operations\nFor parallel operations in a multithreaded environment, use `ThreadedApiClient`:\n\n```python\nfrom runai.api_client import ThreadedApiClient\n\nwith RunaiClient(ThreadedApiClient(config)) as client:\n # These operations can run concurrently\n projects = client.organizations.projects.get_projects()\n```\n\n### Asynchronous Operations\nFor async/await support, use `AsyncApiClient`:\n\n```python\nimport asyncio\nfrom runai.api_client import AsyncApiClient\n\nasync def main():\n async with RunaiClient(AsyncApiClient(config)) as client:\n projects = await client.organizations.projects.get_projects()\n\nasyncio.run(main())\n```\n\n## API Structure\n\nThe client matches the Run:ai REST API documentation structure with three levels of groups:\n\n1. **API Categories**: Top-level groupings (e.g., `organizations`, `authentication_and_authorization`)\n2. **API Groups**: Resource-specific groups within categories (e.g., `projects`, `departments` under `organizations`)\n3. **API Methods**: Individual operations on resources (e.g., `get_projects`, `create_project`)\n\nExample of navigating the API structure:\n\n```python\n# List available API groups in the organizations category\nclient.organizations.options()\n# ['projects', 'departments', 'clusters', 'nodes', ...]\n\n# List available methods in the projects group\nclient.organizations.projects.options()\n# ['get_projects', 'create_project', 'delete_project', ...]\n```\n\n### Deprecated Methods\nDeprecated methods are hidden by default. \\\nTo view both supported and deprecated methods, use the `include_deprecated` flag:\n```python\nclient.organizations.projects.options(include_deprecated=True)\n```\n\n## Client Configuration Options\n\n| Parameter | Type | Description |\n| :-------- | :------- | :-------------------------------- |\n| `client_id` | `string` | **Required**: The Run:ai application client ID, usually representing the application name |\n| `client_secret` | `string` | **Required**: The client secret associated with the Run:ai application |\n| `runai_base_url` | `string` | **Required**: The base URL for the Run:ai instance your organization uses (e.g., `https://myorg.run.ai`) |\n| `bearer_token` | `string` | **Optional**: Bearer token for CLIv2 compatibility. Cannot be used together with client credentials |\n| `verify_ssl` | `bool` | **Optional**: Whether to verify SSL certificates. Default is `True` |\n| `ssl_ca_cert` | `string` | **Optional**: Path to CA certificate file |\n| `cert_file` | `string` | **Optional**: Path to client certificate file |\n| `key_file` | `string` | **Optional**: Path to client key file |\n| `pool_maxsize` | `int` | **Optional**: Maximum number of connections to keep in pool. Default is `4` |\n| `pool_size` | `int` | **Optional**: Initial number of connections in pool. Defaults to `pool_maxsize` |\n| `retry_enabled` | `bool` | **Optional**: Whether to enable request retries. Default is `True` |\n| `retry_max_retries` | `int` | **Optional**: Maximum number of retry attempts. Default is `3` |\n| `retry_backoff_factor` | `float` | **Optional**: Exponential backoff factor between retries. Default is `0.5` |\n| `proxy_url` | `string` | **Optional**: URL for proxy server |\n| `proxy_headers` | `dict` | **Optional**: Additional headers for proxy |\n| `proxy_server_name` | `string` | **Optional**: SNI hostname for TLS connections |\n| `auto_refresh_token` | `bool` | **Optional**: Whether to auto refresh token before expiry. Default is `True` |\n| `token_refresh_margin` | `int` | **Optional**: Seconds before expiry to refresh token. Default is `60` |\n| `debug` | `bool` | **Optional**: Enable debug logging. Default is `False` |\n\n## Authentication Methods\n\nThe client supports three authentication methods:\n\n### 1. Client Credentials\nUse client ID and secret from your Run:ai application:\n```python\nconfig = Configuration(\n client_id=\"your-client-id\",\n client_secret=\"your-client-secret\",\n runai_base_url=\"https://your-org.run.ai\"\n)\n```\n\n### 2. Bearer Token\nDirect authentication using a bearer token:\n```python\nconfig = Configuration(\n bearer_token=\"your-bearer-token\",\n runai_base_url=\"https://your-org.run.ai\"\n)\n```\n\n### 3. CLIv2 Token (Bearer token)\nThe CLIv2 token method is useful for:\n* Local development and testing\n* Scripts running on machines with existing CLI authentication\n* Maintaining consistent authentication with CLI sessions\n* End user operations\n\nRequirements:\n* Run:ai CLI v2 installed\n* Successful `runai login` completed\n* Valid authentication token in CLI config\n\n```python\nfrom runai.cliv2_config_loader import CLIv2Config\n\n# Default config path is ~/.runai\nconfig = CLIv2Config()\n# Or specify a custom path\nconfig = CLIv2Config(cliv2_config_path=\"/path/to/.runai\")\n\ntoken = config.token\nrunai_base_url = config.control_plane_url\ncluster_id = config.cluster_uuid\n\nclient = RunaiClient(\n cluster_id=cluster_id,\n bearer_token=token,\n runai_base_url=runai_base_url\n)\n```\n\n## Examples\n\nThe repo provides Hand-crafted examples showing common use cases.\\\nSee [here](examples/).\n\nThe API client include APIs for all Run:ai UI functionalities.\\\nWe encourage you to explore the client relevant categories if you attempt to run a task that is not shown in the examples.\n\nNote: There are also auto-generated examples under /examples/generated (may require syntax adjustments to run properly)\n## Versioning\nThe Run:ai API is an integral part of the control-plane microservices.\\\nAs the control-plane evolves, APIs may be added, modified, or deprecated.\\\nThis version binding ensures that API changes in the client match the control-plane capabilities.\n\nThe client follows semantic versioning (X.Y.Z) with a special alignment to Run:ai's control-plane versions:\n\n* **X (Major)**: Major changes in the client\n* **Y (Minor)**: Run:ai control-plane version (e.g., 219 for control-plane 2.19)\n* **Z (Patch)**: Small bug fixes and non-breaking changes\n\nFor example:\n```\n1.218.0 # Initial release for control-plane 2.18\n1.218.1 # Patch release for control-plane 2.18\n1.219.0 # Initial release for control-plane 2.19\n```\n\nThis versioning convention ensures that:\n1. Each control-plane version has a matching client version\n2. Client versions clearly indicate their compatible control-plane version\n3. Client breaking changes are managed in major version bumps\n\n## About\nThis package is an open-source project maintained by the Run:ai Professional Services team.\\\nIf you experience any issues or have feature requests, please submit them via the [repository\u2019s issue tracker](https://github.com/runai-professional-services/runapy/issues).\n\n## License\nThis project is licensed under the Apache-2 License. \\\nSee the LICENSE file for details.\n",
"bugtrack_url": null,
"license": "Apache-2",
"summary": "Python client for Run:ai REST API",
"version": "1.222.0",
"project_urls": {
"Homepage": "https://github.com/runai-professional-services/runapy",
"Repository": "https://github.com/runai-professional-services/runapy"
},
"split_keywords": [
"runai",
" kubernetes",
" gpu",
" orchestration"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8899bf04b914f67a19aeb74c08fe465d80a73d0affa72c06062f65b3156c76dc",
"md5": "40f5ff1c93fa40eb2d6a8fc7061498c7",
"sha256": "e1f01be3ca15f3031ddb58a083cbcc0385768032100fefe6b71b88342ac826f5"
},
"downloads": -1,
"filename": "runapy-1.222.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "40f5ff1c93fa40eb2d6a8fc7061498c7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 2429471,
"upload_time": "2025-07-16T10:52:43",
"upload_time_iso_8601": "2025-07-16T10:52:43.236459Z",
"url": "https://files.pythonhosted.org/packages/88/99/bf04b914f67a19aeb74c08fe465d80a73d0affa72c06062f65b3156c76dc/runapy-1.222.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "61caa6b2bb563d53ced4b1b99008dc2f5e7f1a97cee89bbcf96c86d0e23946bb",
"md5": "5c01fa04f8575224e850d0f081550245",
"sha256": "2727cd61a7f58f0be52b9c8f4712fa6ca13ad46f2c221ba13da3d877f9323720"
},
"downloads": -1,
"filename": "runapy-1.222.0.tar.gz",
"has_sig": false,
"md5_digest": "5c01fa04f8575224e850d0f081550245",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 671942,
"upload_time": "2025-07-16T10:52:44",
"upload_time_iso_8601": "2025-07-16T10:52:44.836442Z",
"url": "https://files.pythonhosted.org/packages/61/ca/a6b2bb563d53ced4b1b99008dc2f5e7f1a97cee89bbcf96c86d0e23946bb/runapy-1.222.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 10:52:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "runai-professional-services",
"github_project": "runapy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "runapy"
}
JSON
