Skip to content

capa-cloud/cloud-runtimes-python

Repository files navigation

Cloud Runtimes Python

Cloud Runtimes Python

Multi-Runtime Standard API for Python

Capa Β· Dapr Β· Layotto

Python Version License PyPI Version


πŸ“– 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

Cloud Runtimes Python 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

Cloud Runtimes Python Features

Stable Features

Feature Interface Description Status
πŸ”— Service Invocation RpcService RPC service-to-service communication βœ… Stable
βš™οΈ Configuration ConfigurationService Dynamic configuration management βœ… Stable
πŸ“¨ Pub/Sub PubSubService Publish/Subscribe messaging βœ… Stable
πŸ’Ύ State Management StateService Key-value state storage βœ… Stable
πŸ” Secret Management SecretService Secure secret retrieval βœ… Stable
πŸ“Š Telemetry TelemetryService Logs, metrics, and traces βœ… Stable
πŸ“ File System FileService File storage operations βœ… Stable
πŸ”’ Distributed Lock LockService Distributed locking βœ… Stable

Alpha Features

Feature Interface Description Status
πŸ—„οΈ Database DatabaseService SQL database operations πŸ”¬ Alpha
⏰ Schedule ScheduleService Scheduled task management πŸ”¬ Alpha

🎯 Motivation

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


πŸš€ 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 import CloudRuntimesClient

# Initialize client
client = CloudRuntimesClient(
    endpoint="http://localhost:3500",
    timeout=30.0
)

# Use the RPC service
response = client.rpc.invoke_method(
    service="service-name",
    method="my-method",
    data={"key": "value"}
)

# Use the State service
client.state.save(
    store_name="state-store",
    key="my-key",
    value={"data": "value"}
)

# Retrieve state
state = client.state.get(
    store_name="state-store",
    key="my-key"
)

Async Support

import asyncio
from cloud_runtimes import CloudRuntimesClient

async def main():
    client = CloudRuntimesClient()

    # Async method invocation
    response = await client.rpc.invoke_method_async(
        service="service-name",
        method="my-method",
        data={"key": "value"}
    )

    # Async state operations
    await client.state.save_async(
        store_name="state-store",
        key="my-key",
        value={"data": "value"}
    )

asyncio.run(main())

Runtime Implementations

Choose your runtime implementation:

# For Capa SDK
pip install capa-python

# For Dapr
pip install dapr

# For Layotto (coming soon)
pip install cloud-runtimes-layotto

πŸ“š API Interfaces

Service Invocation

from typing import Any, Dict
from cloud_runtimes.rpc import RpcService

class RpcService:
    def invoke_method(
        self,
        service: str,
        method: str,
        data: Dict[str, Any]
    ) -> Dict[str, Any]:
        """Invoke a method on a remote service."""
        ...

    async def invoke_method_async(
        self,
        service: str,
        method: str,
        data: Dict[str, Any]
    ) -> Dict[str, Any]:
        """Async method invocation."""
        ...

Configuration

from typing import List, Dict
from cloud_runtimes.configuration import ConfigurationService

class ConfigurationService:
    def get_configuration(
        self,
        store_name: str,
        keys: List[str]
    ) -> Dict[str, str]:
        """Get configuration values."""
        ...

    def subscribe_configuration(
        self,
        store_name: str,
        keys: List[str]
    ) -> "ConfigurationSubscription":
        """Subscribe to configuration changes."""
        ...

State Management

from typing import Any, Optional
from cloud_runtimes.state import StateService, StateItem

class StateService:
    def get(
        self,
        store_name: str,
        key: str
    ) -> Optional[Any]:
        """Get a state value."""
        ...

    def save(
        self,
        store_name: str,
        key: str,
        value: Any,
        metadata: Optional[dict] = None
    ) -> None:
        """Save a state value."""
        ...

    def delete(
        self,
        store_name: str,
        key: str
    ) -> None:
        """Delete a state value."""
        ...

🌐 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
capa-python Python Python SDK implementation

🀝 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:


πŸ“œ 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

About

Cloud Runtimes Specification for the Python3.

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Contributors

Languages