mtn-cloud 0.1.0__py3-none-any.whl

mtn_cloud/__init__.py

@@ -0,0 +1,72 @@
+"""
+MTN Cloud Python SDK
+====================
+
+A community-maintained Python SDK for interacting with MTN Cloud (Morpheus).
+
+Quick Start:
+    ```python
+    from mtn_cloud import MTNCloud
+
+    # Initialize client
+    cloud = MTNCloud(token="your-api-token")
+
+    # List instances
+    for instance in cloud.instances.list():
+        print(f"{instance.name}: {instance.status}")
+
+    # Create an instance
+    instance = cloud.instances.create(
+        name="my-app",
+        cloud_id=1,
+        group_id=1,
+        instance_type_code="MTN-CS10",
+        plan_id=6923,
+        layout_id=327,
+    )
+
+    # Instance actions
+    instance.stop()
+    instance.start()
+    instance.delete()
+    ```
+
+Environment Variables:
+    MTN_CLOUD_TOKEN: API access token
+    MTN_CLOUD_URL: API URL (defaults to https://console.cloud.mtn.ng)
+
+Author: Marvellous Osuolale
+License: MIT
+"""
+
+from mtn_cloud.client import MTNCloud
+from mtn_cloud.config import MTNCloudConfig
+from mtn_cloud.exceptions import (
+    AuthenticationError,
+    ForbiddenError,
+    MTNCloudError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+    ValidationError,
+)
+
+__version__ = "0.1.0"
+__author__ = "Marvellous Osuolale"
+__license__ = "MIT"
+__all__ = [
+    # Main client
+    "MTNCloud",
+    # Configuration
+    "MTNCloudConfig",
+    # Exceptions
+    "MTNCloudError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "ForbiddenError",
+    "TimeoutError",
+]

mtn_cloud/client.py

@@ -0,0 +1,278 @@
+"""
+MTN Cloud Client
+================
+
+Main client class for interacting with MTN Cloud.
+"""
+
+from typing import Any
+
+from mtn_cloud.config import MTNCloudConfig
+from mtn_cloud.http import HTTPClient
+from mtn_cloud.models.user import User
+from mtn_cloud.resources.clouds import CloudsResource
+from mtn_cloud.resources.groups import GroupsResource
+from mtn_cloud.resources.instances import InstancesResource
+from mtn_cloud.resources.networks import NetworksResource
+from mtn_cloud.resources.plans import PlansResource
+
+
+class MTNCloud:
+    """
+    MTN Cloud client for interacting with the Morpheus API.
+
+    This is the main entry point for the SDK. Initialize with your
+    API token or credentials to start making API calls.
+
+    Example:
+        ```python
+        from mtn_cloud import MTNCloud
+
+        # Initialize with token
+        cloud = MTNCloud(token="your-api-token")
+
+        # Or with username/password
+        cloud = MTNCloud(
+            username="user@example.com",
+            password="your-password",
+        )
+
+        # List instances
+        for instance in cloud.instances.list():
+            print(f"{instance.name}: {instance.status}")
+
+        # Create an instance
+        instance = cloud.instances.create(
+            name="my-app",
+            cloud_id=1,
+            group_id=1,
+            instance_type_code="MTN-CS10",
+            layout_id=327,
+            plan_id=6923,
+        )
+
+        # Use as context manager
+        with MTNCloud(token="xxx") as cloud:
+            instances = cloud.instances.list()
+        ```
+
+    Attributes:
+        instances: Manage compute instances
+        networks: Manage networks
+        groups: Manage groups (sites)
+        clouds: Manage clouds (zones)
+        plans: Manage service plans
+
+    Environment Variables:
+        MTN_CLOUD_TOKEN: API access token
+        MTN_CLOUD_URL: API URL (default: https://console.cloud.mtn.ng)
+        MTN_CLOUD_TIMEOUT: Request timeout in seconds
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        url: str | None = None,
+        timeout: float | None = None,
+        verify_ssl: bool = True,
+        config: MTNCloudConfig | None = None,
+    ) -> None:
+        """
+        Initialize the MTN Cloud client.
+
+        Args:
+            token: API access token
+            username: Username for authentication
+            password: Password for authentication
+            url: API base URL (default: https://console.cloud.mtn.ng)
+            timeout: Request timeout in seconds
+            verify_ssl: Verify SSL certificates
+            config: Full configuration object (overrides other args)
+        """
+        # Build config from arguments or use provided config
+        if config:
+            self._config = config
+        else:
+            config_kwargs: dict[str, Any] = {}
+
+            if token:
+                config_kwargs["token"] = token
+            if username:
+                config_kwargs["username"] = username
+            if password:
+                config_kwargs["password"] = password
+            if url:
+                config_kwargs["url"] = url
+            if timeout:
+                config_kwargs["timeout"] = timeout
+            if not verify_ssl:
+                config_kwargs["verify_ssl"] = verify_ssl
+
+            self._config = MTNCloudConfig(**config_kwargs)
+
+        # Initialize HTTP client
+        self._http = HTTPClient(self._config)
+
+        # Initialize resource managers
+        self._instances: InstancesResource | None = None
+        self._networks: NetworksResource | None = None
+        self._groups: GroupsResource | None = None
+        self._clouds: CloudsResource | None = None
+        self._plans: PlansResource | None = None
+
+    @property
+    def instances(self) -> InstancesResource:
+        """
+        Access the instances resource manager.
+
+        Example:
+            ```python
+            # List instances
+            instances = cloud.instances.list()
+
+            # Create instance
+            instance = cloud.instances.create(...)
+
+            # Get instance
+            instance = cloud.instances.get(123)
+            ```
+        """
+        if self._instances is None:
+            self._instances = InstancesResource(self._http)
+        return self._instances
+
+    @property
+    def networks(self) -> NetworksResource:
+        """
+        Access the networks resource manager.
+
+        Example:
+            ```python
+            # List networks
+            networks = cloud.networks.list()
+
+            # Get network
+            network = cloud.networks.get(123)
+            ```
+        """
+        if self._networks is None:
+            self._networks = NetworksResource(self._http)
+        return self._networks
+
+    @property
+    def groups(self) -> GroupsResource:
+        """
+        Access the groups resource manager.
+
+        Example:
+            ```python
+            # List groups
+            groups = cloud.groups.list()
+
+            # Get group
+            group = cloud.groups.get(1)
+            ```
+        """
+        if self._groups is None:
+            self._groups = GroupsResource(self._http)
+        return self._groups
+
+    @property
+    def clouds(self) -> CloudsResource:
+        """
+        Access the clouds resource manager.
+
+        Example:
+            ```python
+            # List clouds
+            clouds = cloud.clouds.list()
+
+            # Get cloud
+            c = cloud.clouds.get(1)
+            ```
+        """
+        if self._clouds is None:
+            self._clouds = CloudsResource(self._http)
+        return self._clouds
+
+    @property
+    def plans(self) -> PlansResource:
+        """
+        Access the service plans resource manager.
+
+        Example:
+            ```python
+            # List plans
+            plans = cloud.plans.list()
+
+            # Get plan
+            plan = cloud.plans.get(6923)
+            ```
+        """
+        if self._plans is None:
+            self._plans = PlansResource(self._http)
+        return self._plans
+
+    def whoami(self) -> User:
+        """
+        Get the current authenticated user.
+
+        Returns:
+            Current user information
+
+        Example:
+            ```python
+            user = cloud.whoami()
+            print(f"Logged in as: {user.username}")
+            print(f"Email: {user.email}")
+            ```
+        """
+        response = self._http.get("/whoami")
+        user_data = response.get("user", response)
+        return User.model_validate(user_data)
+
+    def ping(self) -> bool:
+        """
+        Check if the API is reachable and authentication is valid.
+
+        Returns:
+            True if connection is successful
+
+        Example:
+            ```python
+            if cloud.ping():
+                print("Connected!")
+            ```
+        """
+        try:
+            self.whoami()
+            return True
+        except Exception:
+            return False
+
+    @property
+    def config(self) -> MTNCloudConfig:
+        """Get the current configuration."""
+        return self._config
+
+    @property
+    def api_url(self) -> str:
+        """Get the API URL."""
+        return self._config.api_url
+
+    def close(self) -> None:
+        """Close the HTTP session."""
+        self._http.close()
+
+    def __enter__(self) -> "MTNCloud":
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Context manager exit."""
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"<MTNCloud url={self._config.url!r}>"

mtn_cloud/config.py

@@ -0,0 +1,143 @@
+"""
+MTN Cloud SDK Configuration
+===========================
+
+Configuration management using pydantic-settings.
+Supports environment variables and explicit configuration.
+"""
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class MTNCloudConfig(BaseSettings):
+    """
+    Configuration for the MTN Cloud SDK.
+
+    Configuration can be provided via:
+    1. Constructor arguments
+    2. Environment variables (prefixed with MTN_CLOUD_)
+    3. Default values
+
+    Example:
+        ```python
+        # From environment: MTN_CLOUD_TOKEN=xxx
+        config = MTNCloudConfig()
+
+        # Explicit configuration
+        config = MTNCloudConfig(
+            token="your-token",
+            timeout=60,
+        )
+        ```
+
+    Environment Variables:
+        MTN_CLOUD_TOKEN: API access token
+        MTN_CLOUD_URL: API base URL
+        MTN_CLOUD_TIMEOUT: Request timeout in seconds
+        MTN_CLOUD_MAX_RETRIES: Maximum retry attempts
+        MTN_CLOUD_VERIFY_SSL: Enable/disable SSL verification
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="MTN_CLOUD_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # Authentication
+    token: str | None = Field(
+        default=None,
+        description="MTN Cloud API access token",
+    )
+
+    username: str | None = Field(
+        default=None,
+        description="MTN Cloud username (alternative to token)",
+    )
+
+    password: str | None = Field(
+        default=None,
+        description="MTN Cloud password (use with username)",
+    )
+
+    # API Configuration
+    url: str = Field(
+        default="https://console.cloud.mtn.ng",
+        description="MTN Cloud API base URL",
+    )
+
+    api_version: str = Field(
+        default="v1",
+        description="API version (not currently used, for future)",
+    )
+
+    # Request Configuration
+    timeout: float = Field(
+        default=30.0,
+        ge=1.0,
+        le=300.0,
+        description="Request timeout in seconds",
+    )
+
+    max_retries: int = Field(
+        default=3,
+        ge=0,
+        le=10,
+        description="Maximum number of retry attempts",
+    )
+
+    retry_delay: float = Field(
+        default=1.0,
+        ge=0.1,
+        le=60.0,
+        description="Base delay between retries (exponential backoff)",
+    )
+
+    # SSL Configuration
+    verify_ssl: bool = Field(
+        default=True,
+        description="Verify SSL certificates",
+    )
+
+    # Client Configuration
+    user_agent: str = Field(
+        default="mtn-cloud-python/0.1.0",
+        description="User-Agent header for API requests",
+    )
+
+    # Debug
+    debug: bool = Field(
+        default=False,
+        description="Enable debug logging",
+    )
+
+    @field_validator("url")
+    @classmethod
+    def validate_url(cls, v: str) -> str:
+        """Ensure URL doesn't have trailing slash."""
+        return v.rstrip("/")
+
+    @property
+    def api_url(self) -> str:
+        """Get the full API URL."""
+        return f"{self.url}/api"
+
+    @property
+    def has_credentials(self) -> bool:
+        """Check if any authentication credentials are configured."""
+        return bool(self.token or (self.username and self.password))
+
+    def get_auth_method(self) -> str:
+        """Determine the authentication method to use."""
+        if self.token:
+            return "token"
+        elif self.username and self.password:
+            return "credentials"
+        return "none"
+
+
+# Default configuration instance
+default_config = MTNCloudConfig()