Cloud Runtimes Python

Multi-Runtime Standard API for Python

Capa · Dapr · Layotto

---

📖 Introduction

Cloud Runtimes Python provides the Multi-Runtime Standard API for Mecha architecture projects in Python.

This project defines a unified, vendor-neutral API specification that enables Python applications to use standardized interfaces for distributed system capabilities across different runtime implementations.

Supported Runtimes

Runtime	Status	Description
Capa	✅ Used	Primary Mecha SDK implementation
Dapr	📋 Follow	Sidecar runtime reference
Layotto	📋 Follow	MOSN-based sidecar implementation

---

🏗️ Architecture

Module Structure

cloud-runtimes-python/
├── cloud_runtimes/         # Core API package
│   ├── rpc/                # RPC service invocation
│   ├── configuration/      # Configuration management
│   ├── pubsub/             # Pub/Sub messaging
│   ├── state/              # State management
│   ├── secret/             # Secret management
│   └── telemetry/          # Telemetry (logs, metrics, traces)
├── tests/                  # Test suite
├── docs/                   # Documentation
├── setup.py                # Package setup
├── pyproject.toml          # Modern Python packaging
└── requirements.txt        # Dependencies

Key Design Principles:

• API-First: Clean interfaces separate specification from implementation
• Runtime Agnostic: Works with Capa SDK, Dapr, Layotto, and future runtimes
• Pythonic: Follows Python best practices (PEP 8, type hints, async/await)
• Vendor Neutral: No lock-in to specific cloud providers

---

✨ Features

Stable Features

Feature	Interface	Description	Status
🔗 Service Invocation	InvocationRuntimes	Service-to-service communication	✅ Stable
⚙️ Configuration	ConfigurationRuntimes	Dynamic configuration management	✅ Stable
📨 Pub/Sub	PubSubRuntimes	Publish/Subscribe messaging	✅ Stable
💾 State Management	StateRuntimes	Key-value state storage	✅ Stable
🔐 Secret Management	SecretsRuntimes	Secure secret retrieval	✅ Stable
📊 Telemetry	TelemetryRuntimes	Logs, metrics, and traces	✅ Stable
📁 File System	FileRuntimes	File storage operations	✅ Stable
🔒 Distributed Lock	LockRuntimes	Distributed locking	✅ Stable

Alpha Features

Feature	Interface	Description	Status
🗄️ Database	DatabaseRuntimes	SQL database operations	🔬 Alpha

---

🎯 Motivation

Cloud Runtimes Python was created to bring standardized, portable APIs to the Python ecosystem:

• Future plans for Dapr API - Community discussion on API standardization
• Make SDK independent - Decoupling API from implementation
• Decompose core and enhanced APIs - API layering strategy

---

🚀 Getting Started

Installation

From PyPI

pip install cloud-runtimes-python==0.0.1

In a Virtual Environment (Recommended)

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install cloud-runtimes-python==0.0.1

Quick Example

from cloud_runtimes.core import InvocationRuntimes

async def invoke(runtime: InvocationRuntimes) -> bytes:
    return await runtime.invoke_method(
        app_id="service-name",
        method_name="my-method",
        data=b'{"key":"value"}',
    )

Runtime Implementations

This package defines abstract interfaces. Applications must provide an adapter for their chosen runtime and inject those implementations into their own client or service layer.

---

📚 API Interfaces

Service Invocation

InvocationRuntimes defines asynchronous method invocation and registration, plus synchronous invocation helpers.

Configuration

ConfigurationRuntimes defines get, save, delete, subscribe, and unsubscribe operations for configuration stores.

State Management

StateRuntimes defines single and bulk state operations, optimistic-concurrency options, and transactional operations.

---

🌐 Ecosystem

Cloud Runtimes Python is part of the broader Capa Cloud ecosystem:

Project	Language	Description
cloud-runtimes-jvm	Java	JVM API specification
cloud-runtimes-golang	Go	Go API specification

---

🤝 Contributing

We welcome contributions from the Python community!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/capa-cloud/cloud-runtimes-python.git
cd cloud-runtimes-python

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run code quality checks
black .
isort .
flake8

Code Style

We use industry-standard tools for code quality:

• Black - Code formatting
• isort - Import sorting
• flake8 - Linting
• mypy - Type checking

---

📜 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

---

Building portable, vendor-neutral cloud APIs for Python

Capa Cloud · Documentation