py-acs-sdk 1.0.0__tar.gz

py_acs_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: py-acs-sdk
+Version: 1.0.0
+Summary: Python SDK for Apache CloudStack API
+Home-page: https://github.com
+Author: Vimal Kumar Saini
+Author-email: Vimal Saini <vimal.saini25@gmail.com>
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<0.29.0,>=0.28.1
+Requires-Dist: pydantic<3.0.0,>=2.12.5
+Requires-Dist: click<9.0.0,>=8.3.1
+Requires-Dist: opentelemetry-sdk<2.0.0,>=1.40.0
+Dynamic: author
+Dynamic: home-page
+
+# Apache CloudStack Python SDK
+
+A Python SDK for the Apache CloudStack API that provides a simple and type-safe interface to manage resources.
+
+## Features
+
+- 🔐 **Type-Safe** - Built with Pydantic for request/response validation
+- 🚀 **Async Support** - Built on httpx for modern async HTTP requests
+- 📦 **Easy Configuration** - Simple configuration management
+- 🧪 **Well Tested** - Comprehensive test suite with pytest
+- 🔄 **Automatic Retry** - Built-in retry logic with exponential backoff
+- 🔑 **Request Signing** - Automatic HMAC-SHA1 request signing
+- 💻 **CLI Tool** - Command-line interface for quick operations
+
+## Requirements
+
+- Python >= 3.12
+
+## Installation
+
+```bash
+pip install acs-sdk
+```
+
+## Getting Started
+
+### Basic Setup
+
+```python
+from acs_sdk import ApacheCloudStackClient, ApacheCloudStackConfig
+
+# Create a configuration
+config = ApacheCloudStackConfig(
+    endpoint="https://your-cloudstack-endpoint/api",
+    api_key="your_api_key",
+    api_secret="your_api_secret"
+)
+
+# Initialize the CloudStack client
+client = ApacheCloudStackClient(config)
+```
+
+### Making API Calls
+
+```python
+# List users
+response = client.call('listUsers')
+
+# Get user with parameters
+user_response = client.call('getUser', {'userid': '123'})
+
+# Don't forget to close the client
+client.close()
+```
+
+### Async API Calls
+
+```python
+import asyncio
+from acs_sdk import ApacheCloudStackAsyncClient, ApacheCloudStackConfig
+
+async def main():
+    config = ApacheCloudStackConfig(
+        endpoint="https://your-cloudstack-endpoint/api",
+        api_key="your_api_key",
+        api_secret="your_api_secret"
+    )
+    
+    async with ApacheCloudStackAsyncClient(config) as client:
+        response = await client.call_async('listUsers')
+        print(response)
+
+asyncio.run(main())
+```
+
+## Command-Line Interface (CLI)
+
+The SDK includes a CLI tool for quick operations without writing code.
+
+### Setup Environment Variables
+
+```bash
+export CLOUDSTACK_ENDPOINT="https://your-cloudstack-endpoint/api"
+export CLOUDSTACK_API_KEY="your_api_key"
+export CLOUDSTACK_API_SECRET="your_api_secret"
+```
+
+### Available Commands
+
+```bash
+# List all regions
+acs list-regions
+
+# List all users
+acs list-users
+
+# View help
+acs --help
+acs list-regions --help
+```
+
+### CLI Options
+
+You can also provide options directly:
+
+```bash
+acs --endpoint "https://..." --api-key "..." --api-secret "..." list-regions
+```
+
+## Project Structure
+
+```
+src/
+├── acs_sdk/
+│   ├── client/            # HTTP client implementation
+│   ├── core/              # Retry logic and request signing
+│   ├── schemas/           # Configuration schemas
+│   ├── exceptions/        # Custom exceptions
+│   └── cli.py             # Command-line interface
+tests/
+├── unit/                  # Unit tests
+└── conftest.py           # Pytest configuration
+```
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install dependencies with dev tools
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+# Run all tests with coverage
+pytest
+
+# Run specific test file
+pytest tests/unit/test_client.py
+
+# Run with coverage report
+pytest --cov=acs_sdk --cov-report=html
+```
+
+### Code Structure
+
+- **Client** - Handles HTTP requests to Apache CloudStack API
+- **Core** - Retry logic and request signing utilities
+- **Schemas** - Pydantic models for configuration validation
+- **CLI** - Command-line interface for CloudStack operations
+
+## Dependencies
+
+- **httpx** (>=0.28.1) - Modern HTTP client for async support
+- **pydantic** (>=2.12.5) - Data validation and serialization
+- **click** (>=8.3.1) - Command-line interface creation
+
+## License
+
+MIT
+
+## Author
+
+Vimal Saini - vimal.saini25@gmail.com

py_acs_sdk-1.0.0/README.md

@@ -0,0 +1,170 @@
+# Apache CloudStack Python SDK
+
+A Python SDK for the Apache CloudStack API that provides a simple and type-safe interface to manage resources.
+
+## Features
+
+- 🔐 **Type-Safe** - Built with Pydantic for request/response validation
+- 🚀 **Async Support** - Built on httpx for modern async HTTP requests
+- 📦 **Easy Configuration** - Simple configuration management
+- 🧪 **Well Tested** - Comprehensive test suite with pytest
+- 🔄 **Automatic Retry** - Built-in retry logic with exponential backoff
+- 🔑 **Request Signing** - Automatic HMAC-SHA1 request signing
+- 💻 **CLI Tool** - Command-line interface for quick operations
+
+## Requirements
+
+- Python >= 3.12
+
+## Installation
+
+```bash
+pip install acs-sdk
+```
+
+## Getting Started
+
+### Basic Setup
+
+```python
+from acs_sdk import ApacheCloudStackClient, ApacheCloudStackConfig
+
+# Create a configuration
+config = ApacheCloudStackConfig(
+    endpoint="https://your-cloudstack-endpoint/api",
+    api_key="your_api_key",
+    api_secret="your_api_secret"
+)
+
+# Initialize the CloudStack client
+client = ApacheCloudStackClient(config)
+```
+
+### Making API Calls
+
+```python
+# List users
+response = client.call('listUsers')
+
+# Get user with parameters
+user_response = client.call('getUser', {'userid': '123'})
+
+# Don't forget to close the client
+client.close()
+```
+
+### Async API Calls
+
+```python
+import asyncio
+from acs_sdk import ApacheCloudStackAsyncClient, ApacheCloudStackConfig
+
+async def main():
+    config = ApacheCloudStackConfig(
+        endpoint="https://your-cloudstack-endpoint/api",
+        api_key="your_api_key",
+        api_secret="your_api_secret"
+    )
+    
+    async with ApacheCloudStackAsyncClient(config) as client:
+        response = await client.call_async('listUsers')
+        print(response)
+
+asyncio.run(main())
+```
+
+## Command-Line Interface (CLI)
+
+The SDK includes a CLI tool for quick operations without writing code.
+
+### Setup Environment Variables
+
+```bash
+export CLOUDSTACK_ENDPOINT="https://your-cloudstack-endpoint/api"
+export CLOUDSTACK_API_KEY="your_api_key"
+export CLOUDSTACK_API_SECRET="your_api_secret"
+```
+
+### Available Commands
+
+```bash
+# List all regions
+acs list-regions
+
+# List all users
+acs list-users
+
+# View help
+acs --help
+acs list-regions --help
+```
+
+### CLI Options
+
+You can also provide options directly:
+
+```bash
+acs --endpoint "https://..." --api-key "..." --api-secret "..." list-regions
+```
+
+## Project Structure
+
+```
+src/
+├── acs_sdk/
+│   ├── client/            # HTTP client implementation
+│   ├── core/              # Retry logic and request signing
+│   ├── schemas/           # Configuration schemas
+│   ├── exceptions/        # Custom exceptions
+│   └── cli.py             # Command-line interface
+tests/
+├── unit/                  # Unit tests
+└── conftest.py           # Pytest configuration
+```
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install dependencies with dev tools
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+# Run all tests with coverage
+pytest
+
+# Run specific test file
+pytest tests/unit/test_client.py
+
+# Run with coverage report
+pytest --cov=acs_sdk --cov-report=html
+```
+
+### Code Structure
+
+- **Client** - Handles HTTP requests to Apache CloudStack API
+- **Core** - Retry logic and request signing utilities
+- **Schemas** - Pydantic models for configuration validation
+- **CLI** - Command-line interface for CloudStack operations
+
+## Dependencies
+
+- **httpx** (>=0.28.1) - Modern HTTP client for async support
+- **pydantic** (>=2.12.5) - Data validation and serialization
+- **click** (>=8.3.1) - Command-line interface creation
+
+## License
+
+MIT
+
+## Author
+
+Vimal Saini - vimal.saini25@gmail.com

py_acs_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "py-acs-sdk"
+version = "1.0.0"
+description = "Python SDK for Apache CloudStack API"
+authors = [
+    {name = "Vimal Saini",email = "vimal.saini25@gmail.com"}
+]
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = [
+    "httpx (>=0.28.1,<0.29.0)",
+    "pydantic (>=2.12.5,<3.0.0)",
+    "click (>=8.3.1,<9.0.0)",
+    "opentelemetry-sdk (>=1.40.0,<2.0.0)"
+]
+
+[project.scripts]
+acs = "acs_sdk.cli:console"
+
+[dependency-groups]
+dev = [
+    "pytest (>=9.0.2,<10.0.0)",
+    "pytest-cov (>=7.0.0,<8.0.0)",
+    "python-dotenv (>=1.2.2,<2.0.0)",
+    "ruff (>=0.15.7,<0.16.0)",
+    "mypy (>=1.19.1,<2.0.0)"
+]
+
+[tool.poetry]
+packages = [
+    { include = "acs_sdk", from = "src" }
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+addopts = "-ra -q --cov=acs_sdk --cov-report=term-missing"
+
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.mypy]
+strict = true

py_acs_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

py_acs_sdk-1.0.0/setup.py

@@ -0,0 +1,18 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="acs_sdk",
+    version="0.1.0",
+    packages=find_packages(),
+    install_requires=[
+        "httpx (>=0.28.1,<0.29.0)",
+        "pydantic (>=2.12.5,<3.0.0)",
+        "click (>=8.3.1,<9.0.0)",
+        "opentelemetry-sdk (>=1.40.0,<2.0.0)",
+    ],
+    author="Vimal Kumar Saini",
+    description="Python SDK for Apache CloudStack API",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    url="https://github.com",
+)

py_acs_sdk-1.0.0/src/acs_sdk/__init__.py

@@ -0,0 +1,26 @@
+"""Apache CloudStack Python SDK.
+
+This package provides a type-safe, modern Python interface for interacting
+with Apache CloudStack environments. It handles request signing, retries,
+and response parsing automatically.
+
+Main Components:
+    - ApacheCloudStack: High-level entry point for SDK usage
+    - ApacheCloudStackConfig: Configuration management
+    - ApacheCloudStackClient: Low-level HTTP client
+
+Example:
+    >>> from acs_sdk import ApacheCloudStack, ApacheCloudStackConfig
+    >>> config = ApacheCloudStackConfig(
+    ...     api_endpoint='https://api.cloudstack.com/client/api',
+    ...     api_key='your-key',
+    ...     api_secret='your-secret'
+    ... )
+    >>> acs = ApacheCloudStack(config)
+    >>> response = acs.client.call('listUsers')
+"""
+
+from .acs import ApacheCloudStack
+from .schemas.config import ApacheCloudStackConfig
+
+__all__ = ["ApacheCloudStack", "ApacheCloudStackConfig"]

py_acs_sdk-1.0.0/src/acs_sdk/acs.py

@@ -0,0 +1,136 @@
+"""Main module for Apache CloudStack SDK.
+
+This module provides the top-level ApacheCloudStack class that serves as
+the primary interface for interacting with Apache CloudStack environments.
+"""
+
+import logging
+from typing import Dict, Type
+from opentelemetry import trace
+
+from acs_sdk.schemas.config import ApacheCloudStackConfig
+from acs_sdk.client.client import ApacheCloudStackClient
+from acs_sdk.services.account import Account
+from acs_sdk.services.address import Address
+from acs_sdk.services.base import BaseService
+from acs_sdk.services.backup_and_recovery import BackupAndRecovery
+from acs_sdk.services.disk_offering import DiskOffering
+from acs_sdk.services.firewall import Firewall
+from acs_sdk.services.job import Job
+from acs_sdk.services.nat import NAT
+from acs_sdk.services.network import Network
+from acs_sdk.services.network_acl import NetworkACL
+from acs_sdk.services.network_offering import NetworkOffering
+from acs_sdk.services.region import Region
+from acs_sdk.services.security_group import SecurityGroup
+from acs_sdk.services.service_offering import ServiceOffering
+from acs_sdk.services.snapshot import Snapshot
+from acs_sdk.services.ssh import SSH
+from acs_sdk.services.template import Template
+from acs_sdk.services.usage import Usage
+from acs_sdk.services.virtual_machine import VirtualMachine
+from acs_sdk.services.volume import Volume
+from acs_sdk.services.vpc import VPC
+from acs_sdk.services.vpc_offering import VPCOffering
+from acs_sdk.services.zone import Zone
+
+
+class ApacheCloudStack:
+    """High-level interface for Apache CloudStack API interactions.
+
+    This class wraps the CloudStack client and provides a convenient entry point
+    for working with CloudStack resources. It handles initialization of the
+    client with provided configuration.
+
+    Attributes:
+        config (ApacheCloudStackConfig): CloudStack configuration with endpoint
+            and API credentials.
+        client (ApacheCloudStackClient): The underlying HTTP client for API
+            communication.
+
+    Example:
+        >>> config = ApacheCloudStackConfig(
+        ...     api_key='your-key',
+        ...     api_secret='your-secret',
+        ...     endpoint='https://cloudstack.example.com'
+        ... )
+        >>> acs = ApacheCloudStack(config)
+        >>> response = acs.client.call('listUsers')
+    """
+
+    account: "Account"
+    address: "Address"
+    backupandrecovery: "BackupAndRecovery"
+    diskoffering: "DiskOffering"
+    firewall: "Firewall"
+    job: "Job"
+    template: "Template"
+    nat: "NAT"
+    network: "Network"
+    networkacl: "NetworkACL"
+    networkoffering: "NetworkOffering"
+    region: "Region"
+    securitygroup: "SecurityGroup"
+    serviceoffering: "ServiceOffering"
+    snapshot: "Snapshot"
+    ssh: "SSH"
+    usage: "Usage"
+    vm: "VirtualMachine"
+    volume: "Volume"
+    vpc: "VPC"
+    vpcoffering: "VPCOffering"
+    zone: "Zone"
+
+    _service_map: Dict[str, Type["BaseService"]] = {
+        "account": Account,
+        "address": Address,
+        "backupandrecovery": BackupAndRecovery,
+        "diskoffering": DiskOffering,
+        "firewall": Firewall,
+        "job": Job,
+        "nat": NAT,
+        "network": Network,
+        "networkacl": NetworkACL,
+        "networkoffering": NetworkOffering,
+        "region": Region,
+        "securitygroup": SecurityGroup,
+        "serviceoffering": ServiceOffering,
+        "snapshot": Snapshot,
+        "ssh": SSH,
+        "template": Template,
+        "vm": VirtualMachine,
+        "volume": Volume,
+        "vpc": VPC,
+        "vpcoffering": VPCOffering,
+        "usage": Usage,
+        "zone": Zone,
+    }
+
+    def __init__(
+        self,
+        config: ApacheCloudStackConfig,
+        tracer: trace.Tracer = None,
+        logger: logging.Logger = None,
+    ):
+        """Initialize the ApacheCloudStack SDK.
+
+        Args:
+            config (ApacheCloudStackConfig): Configuration object containing
+                CloudStack endpoint URL and API credentials.
+            tracer (trace.Tracer, optional): Tracer for API call tracing.
+            logger (logging.Logger, optional): Logger for API call logging.
+
+        """
+        self.tracer = tracer or trace.get_tracer(__name__)
+        self.logger = logger or logging.getLogger("cloudstack")
+        self.client = ApacheCloudStackClient(config, tracer=self.tracer, logger=self.logger)
+        self._cache = {}
+
+    def __getattr__(self, name):
+        """Dynamically load service classes on demand."""
+        if name in self._service_map:
+            if name not in self._cache:
+                self._cache[name] = self._service_map[name](self.client)
+            return self._cache[name]
+
+        raise AttributeError(f"{name} not found")

py_acs_sdk-1.0.0/src/acs_sdk/cli.py

@@ -0,0 +1,51 @@
+"""Command-line interface module for Apache CloudStack SDK.
+
+This module provides CLI functionality for interacting with Apache CloudStack
+from the command line, offering a convenient alternative to programmatic usage.
+"""
+
+import click
+
+from acs_sdk.commands.service_offering import list_service_offerings
+from acs_sdk.commands.vm import list_vms
+from acs_sdk.commands.volume import list_volumes
+from acs_sdk.commands.zone import list_zones
+from acs_sdk.schemas.config import ApacheCloudStackConfig
+from acs_sdk.commands.region import list_regions
+
+
+@click.group()
+@click.version_option(version="0.1.0")
+@click.option(
+    "--endpoint", envvar="CLOUDSTACK_ENDPOINT", required=True, help="CloudStack API endpoint"
+)
+@click.option("--api-key", envvar="CLOUDSTACK_API_KEY", required=True, help="API key")
+@click.option("--api-secret", envvar="CLOUDSTACK_API_SECRET", required=True, help="API secret")
+@click.pass_context
+def console(ctx, endpoint, api_key, api_secret):
+    """Main entry point for the CloudStack CLI.
+
+    This function serves as the command-line interface entry point for the
+    Apache CloudStack SDK. It's typically invoked when the acs command
+    is run from the terminal.
+
+    Example:
+        $ acs list-users
+        $ acs create-vm --template ubuntu --zone us-west-1
+    """
+    # Store config in context for child commands
+    ctx.ensure_object(dict)
+    ctx.obj["config"] = ApacheCloudStackConfig(
+        api_endpoint=endpoint, api_key=api_key, api_secret=api_secret, timeout=10
+    )
+
+
+console.add_command(list_service_offerings)
+console.add_command(list_regions)
+console.add_command(list_zones)
+console.add_command(list_vms)
+console.add_command(list_volumes)
+
+
+if __name__ == "__main__":
+    console()