mtn-cloud 0.3.2__tar.gz → 0.3.3__tar.gz

{mtn_cloud-0.3.2 → mtn_cloud-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: mtn-cloud
-Version: 0.3.2
+Version: 0.3.3
 Summary: Community Python SDK for MTN Cloud - Deploy and manage cloud resources with ease
 Project-URL: Homepage, https://github.com/mahveotm/mtn-cloud-python
 Project-URL: Documentation, https://github.com/mahveotm/mtn-cloud-python#readme
@@ -405,6 +405,8 @@ Environment variables:
 | `MTN_CLOUD_MAX_RETRIES` | Maximum retry attempts | `3` |
 | `MTN_CLOUD_RETRY_DELAY` | Retry backoff factor | `1.0` |
 | `MTN_CLOUD_VERIFY_SSL` | Enable SSL verification | `true` |
+| `MTN_CLOUD_USER_AGENT` | Application identity appended to the SDK user agent | - |
+| `MTN_CLOUD_DEBUG` | Enable bounded, secret-redacted HTTP debug logs | `false` |
 
 Programmatic configuration:
 
@@ -417,11 +419,21 @@ config = MTNCloudConfig(
     max_retries=5,
     retry_delay=1.5,
     verify_ssl=True,
+    user_agent="my-automation/1.0",  # appended after the required SDK identity
 )
 
 cloud = MTNCloud(config=config)
 ```
 
+Tokens and passwords are stored as masked Pydantic secret values, and debug
+logging recursively redacts credential-shaped fields. The transport retries
+transient failures only for safe read methods (`GET`, `HEAD`, and `OPTIONS`);
+create, update, action, and delete requests are never status-retried automatically.
+
+The default `mtn-cloud-python/<version>` user-agent prefix is required by the
+MTN Cloud API edge. A configured `user_agent` is treated as an application
+suffix so the SDK identity is preserved.
+
 ## Examples
 
 | Script | What it demonstrates |

{mtn_cloud-0.3.2 → mtn_cloud-0.3.3}/README.md

@@ -363,6 +363,8 @@ Environment variables:
 | `MTN_CLOUD_MAX_RETRIES` | Maximum retry attempts | `3` |
 | `MTN_CLOUD_RETRY_DELAY` | Retry backoff factor | `1.0` |
 | `MTN_CLOUD_VERIFY_SSL` | Enable SSL verification | `true` |
+| `MTN_CLOUD_USER_AGENT` | Application identity appended to the SDK user agent | - |
+| `MTN_CLOUD_DEBUG` | Enable bounded, secret-redacted HTTP debug logs | `false` |
 
 Programmatic configuration:
 
@@ -375,11 +377,21 @@ config = MTNCloudConfig(
     max_retries=5,
     retry_delay=1.5,
     verify_ssl=True,
+    user_agent="my-automation/1.0",  # appended after the required SDK identity
 )
 
 cloud = MTNCloud(config=config)
 ```
 
+Tokens and passwords are stored as masked Pydantic secret values, and debug
+logging recursively redacts credential-shaped fields. The transport retries
+transient failures only for safe read methods (`GET`, `HEAD`, and `OPTIONS`);
+create, update, action, and delete requests are never status-retried automatically.
+
+The default `mtn-cloud-python/<version>` user-agent prefix is required by the
+MTN Cloud API edge. A configured `user_agent` is treated as an application
+suffix so the SDK identity is preserved.
+
 ## Examples
 
 | Script | What it demonstrates |

{mtn_cloud-0.3.2 → mtn_cloud-0.3.3}/docs/advanced-cookbook.md

@@ -5,14 +5,16 @@ Production-friendly patterns for robust automation.
 ## Configure a Resilient Client
 
 ```python
-from mtn_cloud import MTNCloud
+from mtn_cloud import MTNCloud, MTNCloudConfig
 
-cloud = MTNCloud(
+config = MTNCloudConfig(
     token="your-api-token",
     timeout=45,
-    # Retry values are controlled through MTNCloudConfig defaults:
-    # max_retries=3, retry_delay=1.0
+    max_retries=3,
+    retry_delay=1.0,
+    user_agent="my-automation/1.0",
 )
+cloud = MTNCloud(config=config)
 ```
 
 Use environment variables for deployment:
@@ -24,6 +26,15 @@ export MTN_CLOUD_MAX_RETRIES="5"
 export MTN_CLOUD_RETRY_DELAY="1.5"
 ```
 
+Retries apply only to safe reads (`GET`, `HEAD`, and `OPTIONS`). The SDK does
+not automatically retry provisioning, actions, updates, or deletes because a
+server or proxy error does not prove that a write was rejected before execution.
+
+`user_agent` adds an application identity after the SDK's required
+`mtn-cloud-python/<version>` prefix. Debug logging is bounded and recursively
+redacts tokens, passwords, access keys, secret keys, cookies, authorization
+values, and similar credential fields.
+
 ## Pattern: Idempotent "Get or Create"
 
 ```python

{mtn_cloud-0.3.2 → mtn_cloud-0.3.3}/docs/api-reference/client.md

@@ -1,6 +1,6 @@
 # Client: `MTNCloud`
 
-### `MTNCloud(token=None, username=None, password=None, url=None, timeout=None, verify_ssl=True, config=None)`
+### `MTNCloud(token=None, username=None, password=None, url=None, timeout=None, verify_ssl=None, config=None)`
 
 Creates an SDK client and lazy-loads resource managers.
 
@@ -10,12 +10,27 @@ Creates an SDK client and lazy-loads resource managers.
     - `username`, `password`: OAuth password-grant alternative
     - `url`: MTN Cloud base console URL, no `/api` needed
     - `timeout`: request timeout in seconds
-    - `verify_ssl`: enable/disable TLS certificate validation
+    - `verify_ssl`: enable/disable TLS certificate validation; when omitted,
+      `MTN_CLOUD_VERIFY_SSL` or the configuration default is used
     - `config`: explicit `MTNCloudConfig` object (overrides other args)
 - Returns: `MTNCloud`
 - Raises:
     - `pydantic.ValidationError` if config values violate `MTNCloudConfig` constraints
 
+Tokens and passwords are stored as masked secret values. Use
+`config.get_token_value()` or `config.get_password_value()` only when an explicit
+integration needs the underlying value; normal SDK usage never needs to reveal
+them.
+
+The transport:
+
+- preserves the `mtn-cloud-python/<version>` user-agent identity required by the
+  MTN API edge;
+- recursively redacts secrets from debug logs and raised error response payloads;
+- retries 429 and transient 5xx responses only for `GET`, `HEAD`, and `OPTIONS`;
+- does not automatically status-retry `POST`, `PUT`, `PATCH`, or `DELETE` calls;
+- handles both delta-seconds and HTTP-date `Retry-After` headers.
+
 ### `whoami() -> User`
 
 - Endpoint: `GET /api/whoami`
@@ -41,4 +56,3 @@ Connectivity/auth convenience check.
 - Parameters: none
 - Returns: `None`
 - Raises: none
-

{mtn_cloud-0.3.2 → mtn_cloud-0.3.3}/src/mtn_cloud/_version.py

@@ -1,3 +1,3 @@
 """Package version metadata."""
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"

{mtn_cloud-0.3.2 → mtn_cloud-0.3.3}/src/mtn_cloud/client.py

@@ -82,7 +82,7 @@ class MTNCloud:
         password: str | None = None,
         url: str | None = None,
         timeout: float | None = None,
-        verify_ssl: bool = True,
+        verify_ssl: bool | None = None,
         config: MTNCloudConfig | None = None,
     ) -> None:
         """
@@ -94,7 +94,8 @@ class MTNCloud:
             password: Password for authentication
             url: API base URL (default: https://console.cloud.mtn.ng)
             timeout: Request timeout in seconds
-            verify_ssl: Verify SSL certificates
+            verify_ssl: Verify SSL certificates. When omitted, configuration and
+                environment settings are respected.
             config: Full configuration object (overrides other args)
         """
         if config:
@@ -102,17 +103,17 @@ class MTNCloud:
         else:
             config_kwargs: dict[str, Any] = {}
 
-            if token:
+            if token is not None:
                 config_kwargs["token"] = token
-            if username:
+            if username is not None:
                 config_kwargs["username"] = username
-            if password:
+            if password is not None:
                 config_kwargs["password"] = password
-            if url:
+            if url is not None:
                 config_kwargs["url"] = url
-            if timeout:
+            if timeout is not None:
                 config_kwargs["timeout"] = timeout
-            if not verify_ssl:
+            if verify_ssl is not None:
                 config_kwargs["verify_ssl"] = verify_ssl
 
             self._config = MTNCloudConfig(**config_kwargs)

{mtn_cloud-0.3.2 → mtn_cloud-0.3.3}/src/mtn_cloud/config.py

@@ -1,6 +1,6 @@
 """Configuration models and defaults for the MTN Cloud SDK."""
 
-from pydantic import Field, field_validator
+from pydantic import Field, SecretStr, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from mtn_cloud._version import __version__
@@ -32,7 +32,10 @@ class MTNCloudConfig(BaseSettings):
         MTN_CLOUD_URL: API base URL
         MTN_CLOUD_TIMEOUT: Request timeout in seconds
         MTN_CLOUD_MAX_RETRIES: Maximum retry attempts
+        MTN_CLOUD_RETRY_DELAY: Base retry backoff factor
         MTN_CLOUD_VERIFY_SSL: Enable/disable SSL verification
+        MTN_CLOUD_USER_AGENT: Application identity appended to the SDK user agent
+        MTN_CLOUD_DEBUG: Enable secret-redacted debug logging
     """
 
     model_config = SettingsConfigDict(
@@ -43,7 +46,7 @@ class MTNCloudConfig(BaseSettings):
         extra="ignore",
     )
 
-    token: str | None = Field(
+    token: SecretStr | None = Field(
         default=None,
         description="MTN Cloud API access token",
     )
@@ -53,7 +56,7 @@ class MTNCloudConfig(BaseSettings):
         description="MTN Cloud username (alternative to token)",
     )
 
-    password: str | None = Field(
+    password: SecretStr | None = Field(
         default=None,
         description="MTN Cloud password (use with username)",
     )
@@ -96,7 +99,7 @@ class MTNCloudConfig(BaseSettings):
 
     user_agent: str = Field(
         default=DEFAULT_USER_AGENT,
-        description="User-Agent header for API requests",
+        description="Application identity appended to the MTN-compatible SDK user agent",
     )
 
     debug: bool = Field(
@@ -110,6 +113,19 @@ class MTNCloudConfig(BaseSettings):
         """Ensure URL doesn't have trailing slash."""
         return v.rstrip("/")
 
+    @field_validator("user_agent")
+    @classmethod
+    def normalize_user_agent(cls, value: str) -> str:
+        """Preserve the SDK identity required by MTN's API edge."""
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("user_agent cannot be empty")
+        if "\r" in normalized or "\n" in normalized:
+            raise ValueError("user_agent cannot contain line breaks")
+        if DEFAULT_USER_AGENT in normalized:
+            return normalized
+        return f"{DEFAULT_USER_AGENT} {normalized}"
+
     @property
     def api_url(self) -> str:
         """Get the full API URL."""
@@ -120,6 +136,14 @@ class MTNCloudConfig(BaseSettings):
         """Check if any authentication credentials are configured."""
         return bool(self.token or (self.username and self.password))
 
+    def get_token_value(self) -> str | None:
+        """Return the token for the HTTP transport without exposing it in reprs."""
+        return self.token.get_secret_value() if self.token is not None else None
+
+    def get_password_value(self) -> str | None:
+        """Return the password for the authentication transport."""
+        return self.password.get_secret_value() if self.password is not None else None
+
     def get_auth_method(self) -> str:
         """Determine the authentication method to use."""
         if self.token:
@@ -127,7 +151,3 @@ class MTNCloudConfig(BaseSettings):
         elif self.username and self.password:
             return "credentials"
         return "none"
-
-
-# Shared default configuration for callers that want module-level settings.
-default_config = MTNCloudConfig()

{mtn_cloud-0.3.2 → mtn_cloud-0.3.3}/src/mtn_cloud/http.py

@@ -1,9 +1,14 @@
 """Low-level HTTP transport, authentication, and error mapping."""
 
 import logging
+import math
+from collections.abc import Mapping, Sequence
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
 from typing import Any, Literal
 
 import requests
+from pydantic import SecretStr
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
@@ -26,6 +31,52 @@ from mtn_cloud.exceptions import (
 logger = logging.getLogger("mtn_cloud.http")
 
 HTTPMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
+SAFE_RETRY_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+REDACTED = "<redacted>"
+MAX_LOG_VALUE_LENGTH = 4_096
+
+_SENSITIVE_KEY_FRAGMENTS = (
+    "accesskey",
+    "accesstoken",
+    "apikey",
+    "authorization",
+    "cookie",
+    "credential",
+    "password",
+    "passwd",
+    "privatekey",
+    "secret",
+    "token",
+)
+
+
+def _is_sensitive_key(key: Any) -> bool:
+    """Return whether a mapping key conventionally contains secret material."""
+    normalized = "".join(character for character in str(key).lower() if character.isalnum())
+    return any(fragment in normalized for fragment in _SENSITIVE_KEY_FRAGMENTS)
+
+
+def _redact_sensitive(value: Any, *, known_secrets: Sequence[str] = ()) -> Any:
+    """Recursively redact secret fields and known secret values."""
+    if isinstance(value, SecretStr):
+        return REDACTED
+    if isinstance(value, Mapping):
+        return {
+            key: REDACTED
+            if _is_sensitive_key(key)
+            else _redact_sensitive(item, known_secrets=known_secrets)
+            for key, item in value.items()
+        }
+    if isinstance(value, list | tuple | set | frozenset):
+        return [_redact_sensitive(item, known_secrets=known_secrets) for item in value]
+    if isinstance(value, bytes):
+        return f"<bytes:{len(value)}>"
+    if isinstance(value, str):
+        redacted = value
+        for secret in sorted({secret for secret in known_secrets if secret}, key=len, reverse=True):
+            redacted = redacted.replace(secret, REDACTED)
+        return redacted
+    return value
 
 
 class HTTPClient:
@@ -53,7 +104,7 @@ class HTTPClient:
         self._token: str | None = None
 
         if config.token:
-            self._token = config.token
+            self._token = config.get_token_value()
 
     @property
     def session(self) -> requests.Session:
@@ -70,7 +121,7 @@ class HTTPClient:
             total=self.config.max_retries,
             backoff_factor=self.config.retry_delay,
             status_forcelist=[429, 500, 502, 503, 504],
-            allowed_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
+            allowed_methods=SAFE_RETRY_METHODS,
             respect_retry_after_header=True,
             raise_on_status=False,
         )
@@ -119,7 +170,7 @@ class HTTPClient:
         }
         data = {
             "username": self.config.username,
-            "password": self.config.password,
+            "password": self.config.get_password_value(),
         }
 
         try:
@@ -131,19 +182,26 @@ class HTTPClient:
             )
 
             if response.status_code != 200:
-                response_payload: dict[str, Any] | None
-                try:
-                    response_payload = response.json() if response.text else None
-                except ValueError:
-                    response_payload = {"raw": response.text} if response.text else None
+                response_payload = self._parse_response_body(response)
+                safe_payload = self._redact(response_payload)
                 raise AuthenticationError(
-                    f"Authentication failed: {response.text}",
+                    self._extract_error_message(safe_payload),
                     status_code=response.status_code,
-                    response=response_payload,
+                    response=safe_payload,
                 )
 
-            result = response.json()
-            token: str = result["access_token"]
+            try:
+                result = response.json()
+                token = result["access_token"]
+                if not isinstance(token, str) or not token:
+                    raise ValueError("access_token must be a non-empty string")
+            except (KeyError, TypeError, ValueError) as exc:
+                safe_payload = self._redact(self._parse_response_body(response))
+                raise AuthenticationError(
+                    "Authentication response did not contain a valid access token.",
+                    status_code=response.status_code,
+                    response=safe_payload,
+                ) from exc
             self._token = token
 
             logger.debug("Successfully authenticated")
@@ -197,16 +255,18 @@ class HTTPClient:
         """
         url = self._build_url(path)
         request_headers = {**self._get_headers(), **(headers or {})}
-        request_timeout = timeout or self.config.timeout
+        request_timeout = timeout if timeout is not None else self.config.timeout
 
         if self.config.debug:
-            logger.debug(f"Request: {method} {url}")
+            logger.debug("Request: %s %s", method, url)
             if params:
-                logger.debug(f"Params: {params}")
+                logger.debug("Params: %s", self._format_for_log(params))
             if json:
-                logger.debug(f"JSON: {json}")
+                logger.debug("JSON: %s", self._format_for_log(json))
+            if data:
+                logger.debug("Data: %s", self._format_for_log(data))
             if files:
-                logger.debug(f"Files: {list(files.keys())}")
+                logger.debug("Multipart fields: %s", sorted(files))
 
         try:
             response = self.session.request(
@@ -253,27 +313,25 @@ class HTTPClient:
         """
         request_id = response.headers.get("X-Request-Id")
 
-        try:
-            body = response.json() if response.text else {}
-        except ValueError:
-            body = {"raw": response.text}
+        body = self._parse_response_body(response)
 
         if self.config.debug:
-            logger.debug(f"Response: {response.status_code}")
-            logger.debug(f"Body: {body}")
+            logger.debug("Response: %s", response.status_code)
+            logger.debug("Body: %s", self._format_for_log(body))
 
         if 200 <= response.status_code < 300:
             return body
 
-        error_message = self._extract_error_message(body)
+        safe_body = self._redact(body)
+        error_message = self._extract_error_message(safe_body)
         status_code = response.status_code
 
         if status_code == 400:
-            errors = body.get("errors", [])
+            errors = safe_body.get("errors", [])
             raise ValidationError(
                 message=error_message,
                 errors=errors,
-                response=body,
+                response=safe_body,
                 request_id=request_id,
             )
 
@@ -283,47 +341,49 @@ class HTTPClient:
             raise AuthenticationError(
                 message=error_message,
                 status_code=status_code,
-                response=body,
+                response=safe_body,
                 request_id=request_id,
             )
 
         if status_code == 403:
             raise ForbiddenError(
                 message=error_message,
-                response=body,
+                response=safe_body,
                 request_id=request_id,
             )
 
         if status_code == 404:
             raise NotFoundError(
                 message=error_message,
-                response=body,
+                response=safe_body,
                 request_id=request_id,
             )
 
         if status_code == 402:
             raise QuotaExceededError(
                 message=error_message,
-                quota_type=body.get("quotaType") or body.get("quota"),
-                current=(body.get("current") if isinstance(body.get("current"), int) else None),
-                limit=body.get("limit") if isinstance(body.get("limit"), int) else None,
-                response=body,
+                quota_type=safe_body.get("quotaType") or safe_body.get("quota"),
+                current=(
+                    safe_body.get("current") if isinstance(safe_body.get("current"), int) else None
+                ),
+                limit=(safe_body.get("limit") if isinstance(safe_body.get("limit"), int) else None),
+                response=safe_body,
                 request_id=request_id,
             )
 
         if status_code == 409:
             raise ResourceConflictError(
                 message=error_message,
-                response=body,
+                response=safe_body,
                 request_id=request_id,
             )
 
         if status_code == 429:
-            retry_after = response.headers.get("Retry-After")
+            retry_after = self._parse_retry_after(response.headers.get("Retry-After"))
             raise RateLimitError(
                 message=error_message,
-                retry_after=int(retry_after) if retry_after else None,
-                response=body,
+                retry_after=retry_after,
+                response=safe_body,
                 request_id=request_id,
             )
 
@@ -331,14 +391,14 @@ class HTTPClient:
             raise ServerError(
                 message=error_message,
                 status_code=status_code,
-                response=body,
+                response=safe_body,
                 request_id=request_id,
             )
 
         raise MTNCloudError(
             message=error_message,
             status_code=status_code,
-            response=body,
+            response=safe_body,
             request_id=request_id,
         )
 
@@ -372,6 +432,81 @@ class HTTPClient:
 
         return "Unknown error"
 
+    def _known_secrets(self) -> tuple[str, ...]:
+        """Return configured secret values for value-based redaction."""
+        return tuple(
+            secret
+            for secret in (
+                self._token,
+                self.config.get_token_value(),
+                self.config.get_password_value(),
+            )
+            if secret
+        )
+
+    def _redact(self, value: Any) -> Any:
+        """Redact configured and conventionally named secrets."""
+        return _redact_sensitive(value, known_secrets=self._known_secrets())
+
+    def _format_for_log(self, value: Any) -> str:
+        """Return a bounded, redacted representation suitable for debug logs."""
+        formatted = repr(self._redact(value))
+        if len(formatted) <= MAX_LOG_VALUE_LENGTH:
+            return formatted
+        return f"{formatted[:MAX_LOG_VALUE_LENGTH]}... <truncated>"
+
+    def _parse_response_body(self, response: requests.Response) -> dict[str, Any]:
+        """Normalize JSON bodies and safely describe non-JSON API errors."""
+        if not response.text:
+            return {}
+
+        try:
+            parsed = response.json()
+        except ValueError:
+            if 200 <= response.status_code < 300:
+                return {"raw": response.text}
+
+            content_type = response.headers.get("Content-Type", "unknown content type")
+            return {
+                "message": (
+                    f"Non-JSON response from API (HTTP {response.status_code}, {content_type})"
+                ),
+                "contentType": content_type,
+                "contentLength": len(response.content),
+            }
+
+        if isinstance(parsed, dict):
+            return parsed
+        return {"data": parsed}
+
+    @staticmethod
+    def _parse_retry_after(
+        value: str | None,
+        *,
+        now: datetime | None = None,
+    ) -> int | None:
+        """Parse Retry-After delta-seconds or an HTTP date into whole seconds."""
+        if not value:
+            return None
+
+        normalized = value.strip()
+        try:
+            return max(0, int(normalized))
+        except ValueError:
+            pass
+
+        try:
+            retry_at = parsedate_to_datetime(normalized)
+        except (TypeError, ValueError, OverflowError):
+            return None
+
+        if retry_at.tzinfo is None:
+            retry_at = retry_at.replace(tzinfo=timezone.utc)
+        reference = now or datetime.now(timezone.utc)
+        if reference.tzinfo is None:
+            reference = reference.replace(tzinfo=timezone.utc)
+        return max(0, math.ceil((retry_at - reference).total_seconds()))
+
     # Convenience methods
     def get(
         self,
@@ -432,7 +567,7 @@ class HTTPClient:
         """
         url = self._build_url(path)
         request_headers = {**self._get_headers(), **(headers or {})}
-        request_timeout = timeout or self.config.timeout
+        request_timeout = timeout if timeout is not None else self.config.timeout
 
         try:
             response = self.session.request(