aioscaleway 0.1.0__py3-none-any.whl

aioscaleway/__init__.py

@@ -0,0 +1,48 @@
+from aioscaleway._client import ScalewayClient
+from aioscaleway._enums import OpenStrEnum
+from aioscaleway._errors import (
+    ConflictError,
+    DeniedAuthenticationError,
+    InvalidArgumentsError,
+    OutOfStockError,
+    PermissionsDeniedError,
+    PreconditionFailedError,
+    QuotasExceededError,
+    ResourceExpiredError,
+    ResourceNotFoundError,
+    ScalewayAPIError,
+    ScalewayConfigurationError,
+    ScalewayError,
+    ScalewayTransportError,
+    ServerError,
+    TooManyRequestsError,
+    TransientStateError,
+)
+from aioscaleway._models import Money, ScalewayModel
+from aioscaleway._root import Scaleway
+from aioscaleway._settings import ScalewaySettings
+
+__all__ = [
+    "ConflictError",
+    "DeniedAuthenticationError",
+    "InvalidArgumentsError",
+    "Money",
+    "OpenStrEnum",
+    "OutOfStockError",
+    "PermissionsDeniedError",
+    "PreconditionFailedError",
+    "QuotasExceededError",
+    "ResourceExpiredError",
+    "ResourceNotFoundError",
+    "Scaleway",
+    "ScalewayAPIError",
+    "ScalewayClient",
+    "ScalewayModel",
+    "ScalewayConfigurationError",
+    "ScalewayError",
+    "ScalewaySettings",
+    "ScalewayTransportError",
+    "ServerError",
+    "TooManyRequestsError",
+    "TransientStateError",
+]

aioscaleway/_client.py

@@ -0,0 +1,295 @@
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
+from enum import Enum
+from http import HTTPStatus
+from types import TracebackType
+from typing import Any, Self
+from urllib.parse import quote
+
+from httpx2 import (
+    AsyncBaseTransport,
+    AsyncClient,
+    ConnectError,
+    ConnectTimeout,
+    Response,
+    TransportError,
+)
+from pydantic import BaseModel
+from stamina import retry_context
+from whenever import Date, Instant
+
+from aioscaleway._errors import (
+    ScalewayAPIError,
+    ScalewayConfigurationError,
+    ScalewayTransportError,
+    api_error,
+)
+from aioscaleway._settings import ScalewaySettings
+
+IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE"})
+RETRYABLE_STATUSES = frozenset(
+    {
+        HTTPStatus.TOO_MANY_REQUESTS,
+        HTTPStatus.BAD_GATEWAY,
+        HTTPStatus.SERVICE_UNAVAILABLE,
+        HTTPStatus.GATEWAY_TIMEOUT,
+    }
+)
+NEVER_PROCESSED_STATUSES = frozenset(
+    {HTTPStatus.TOO_MANY_REQUESTS, HTTPStatus.SERVICE_UNAVAILABLE}
+)
+type QueryValue = str | int | float | bool | Enum | Instant | Date | None
+type Query = Mapping[str, QueryValue | list[Any]]
+type QueryPairs = list[tuple[str, str | int | float | bool | None]]
+
+
+def retry_decision(method: str, error: Exception) -> bool | float:
+    """Tell stamina whether to retry, waiting Retry-After seconds when given."""
+    if isinstance(error, ScalewayAPIError):
+        if error.status_code not in RETRYABLE_STATUSES:
+            return False
+        if method not in IDEMPOTENT_METHODS and (
+            error.status_code not in NEVER_PROCESSED_STATUSES
+        ):
+            return False
+        retry_after = error.headers.get("retry-after", "")
+        return float(retry_after) if retry_after.isdigit() else True
+    if isinstance(error, ScalewayTransportError):
+        return method in IDEMPOTENT_METHODS or isinstance(
+            error.__cause__, ConnectError | ConnectTimeout
+        )
+    return False
+
+
+def query_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, Enum):
+        return str(value.value)
+    if isinstance(value, Instant | Date):
+        return value.format_iso()
+    return str(value)
+
+
+def encode_query(params: Query | None) -> QueryPairs:
+    pairs: QueryPairs = []
+    for name, value in (params or {}).items():
+        if value is None:
+            continue
+        values = value if isinstance(value, list) else [value]
+        pairs.extend((name, query_value(item)) for item in values if item is not None)
+    return pairs
+
+
+def encode_body(value: Any) -> Any:
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json", by_alias=True, exclude_unset=True)
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Instant | Date):
+        return value.format_iso()
+    if isinstance(value, dict):
+        return {
+            key: encode_body(item) for key, item in value.items() if item is not None
+        }
+    if isinstance(value, list | tuple):
+        return [encode_body(item) for item in value]
+    return value
+
+
+class ScalewayClient:
+    """Authenticated, retrying HTTP access to the Scaleway API (`Scaleway().raw`)."""
+
+    def __init__(
+        self,
+        settings: ScalewaySettings | None = None,
+        *,
+        transport: AsyncBaseTransport | None = None,
+        http_client: AsyncClient | None = None,
+    ) -> None:
+        self.settings = ScalewaySettings() if settings is None else settings
+        self._owns_http_client = http_client is None
+        self._http = http_client or AsyncClient(
+            base_url=self.settings.api_url,
+            transport=transport,
+            timeout=self.settings.timeout,
+        )
+
+    @property
+    def http_client(self) -> AsyncClient:
+        return self._http
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_http_client:
+            await self._http.aclose()
+
+    def region(self, region: str | None) -> str:
+        value = region or self.settings.default_region
+        if not value:
+            raise ScalewayConfigurationError(
+                "No region given and no default_region configured (SCW_DEFAULT_REGION)."
+            )
+        return value
+
+    def zone(self, zone: str | None) -> str:
+        value = zone or self.settings.default_zone
+        if not value:
+            raise ScalewayConfigurationError(
+                "No zone given and no default_zone configured (SCW_DEFAULT_ZONE)."
+            )
+        return value
+
+    def project_id(self, project_id: str | None) -> str | None:
+        return project_id or self.settings.default_project_id
+
+    def organization_id(self, organization_id: str | None) -> str | None:
+        return organization_id or self.settings.default_organization_id
+
+    def owner(
+        self,
+        *,
+        project_id: str | None,
+        organization_id: str | None,
+        keys: tuple[str, str] = ("project_id", "organization_id"),
+    ) -> dict[str, str]:
+        """Pick the project or the organization a resource belongs to."""
+        project_key, organization_key = keys
+        if project_id:
+            return {project_key: project_id}
+        if organization_id:
+            return {organization_key: organization_id}
+        if self.settings.default_project_id:
+            return {project_key: self.settings.default_project_id}
+        if self.settings.default_organization_id:
+            return {organization_key: self.settings.default_organization_id}
+        return {}
+
+    @staticmethod
+    def path(template: str, **values: Any) -> str:
+        if any(value is None or value == "" for value in values.values()):
+            missing = [name for name, value in values.items() if value in (None, "")]
+            raise ScalewayConfigurationError(
+                f"Empty path parameter: {', '.join(missing)}."
+            )
+        return template.format(
+            **{
+                name: quote(query_value(value), safe="")
+                for name, value in values.items()
+            }
+        )
+
+    def _headers(self, extra: Mapping[str, str] | None) -> dict[str, str]:
+        headers = {"User-Agent": self.settings.user_agent}
+        if self.settings.secret_key is not None:
+            headers["X-Auth-Token"] = self.settings.secret_key.get_secret_value()
+        headers.update(extra or {})
+        return headers
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Query | None = None,
+        body: Any = None,
+        content: bytes | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Response:
+        """Send one request, retried on throttling and transient failures."""
+        method = method.upper()
+        query = encode_query(params)
+        json_body = None if body is None else encode_body(body)
+        request_headers = self._headers(headers)
+        async for attempt in retry_context(
+            on=lambda error: retry_decision(method, error),
+            attempts=self.settings.retry_attempts,
+            timeout=self.settings.retry_timeout,
+            wait_initial=self.settings.retry_wait_initial,
+            wait_max=self.settings.retry_wait_max,
+        ):
+            with attempt:
+                return await self._send(
+                    method, path, query, json_body, content, request_headers
+                )
+        raise AssertionError("unreachable: stamina either returns or raises")
+
+    async def _send(
+        self,
+        method: str,
+        path: str,
+        query: QueryPairs,
+        json_body: Any,
+        content: bytes | None,
+        headers: dict[str, str],
+    ) -> Response:
+        try:
+            response = await self._http.request(
+                method,
+                path,
+                params=query,
+                json=json_body,
+                content=content,
+                headers=headers,
+            )
+        except TransportError as error:
+            raise ScalewayTransportError(method, path, repr(error)) from error
+        if response.is_error:
+            try:
+                error_body: Any = response.json()
+            except ValueError:
+                error_body = response.text
+            raise api_error(
+                method,
+                str(response.url),
+                response.status_code,
+                error_body,
+                dict(response.headers),
+            )
+        return response
+
+    async def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Query | None = None,
+        body: Any = None,
+        content: bytes | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        response = await self.request(
+            method, path, params=params, body=body, content=content, headers=headers
+        )
+        if response.status_code == HTTPStatus.NO_CONTENT or not response.content:
+            return None
+        return response.json()
+
+
+async def paginate[Page, Item](
+    fetch: Callable[[int], Awaitable[Page]],
+    items: Callable[[Page], list[Item]],
+    total: Callable[[Page], int | None],
+) -> AsyncIterator[Item]:
+    """Walk the `page` / `page_size` pagination until `total_count` items are read."""
+    page_number = 1
+    seen = 0
+    while True:
+        page = await fetch(page_number)
+        batch = items(page)
+        for item in batch:
+            yield item
+        seen += len(batch)
+        expected = total(page)
+        if not batch or (expected is not None and seen >= expected):
+            return
+        page_number += 1

aioscaleway/_enums.py

@@ -0,0 +1,15 @@
+from enum import StrEnum
+from typing import Self
+
+
+class OpenStrEnum(StrEnum):
+    """A string enum that accepts values added to the API after generation."""
+
+    @classmethod
+    def _missing_(cls, value: object) -> Self | None:
+        if not isinstance(value, str):
+            return None
+        member = str.__new__(cls, value)
+        member._name_ = value.upper()
+        member._value_ = value
+        return member

aioscaleway/_errors.py

@@ -0,0 +1,133 @@
+from http import HTTPStatus
+from typing import Any
+
+
+class ScalewayError(Exception):
+    """Base class of every error raised by aioscaleway."""
+
+
+class ScalewayConfigurationError(ScalewayError):
+    """A value the request needs is neither given nor configured."""
+
+
+class ScalewayTransportError(ScalewayError):
+    """The API could not be reached, or the connection broke."""
+
+    def __init__(self, method: str, url: str, reason: str) -> None:
+        super().__init__(f"{method} {url} failed: {reason}")
+        self.method = method
+        self.url = url
+
+
+class ScalewayAPIError(ScalewayError):
+    """The API answered with an error status."""
+
+    def __init__(
+        self,
+        method: str,
+        url: str,
+        status_code: int,
+        body: Any,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        self.method = method
+        self.url = url
+        self.status_code = status_code
+        self.body = body
+        self.headers = headers or {}
+        details = body if isinstance(body, dict) else {}
+        self.type: str | None = details.get("type")
+        self.message: str = str(details.get("message") or body or "")
+        self.details: Any = details.get("details")
+        super().__init__(f"{method} {url} answered {status_code}: {self.message}")
+
+
+class InvalidArgumentsError(ScalewayAPIError):
+    pass
+
+
+class DeniedAuthenticationError(ScalewayAPIError):
+    pass
+
+
+class PermissionsDeniedError(ScalewayAPIError):
+    pass
+
+
+class QuotasExceededError(ScalewayAPIError):
+    pass
+
+
+class ResourceNotFoundError(ScalewayAPIError):
+    pass
+
+
+class ConflictError(ScalewayAPIError):
+    pass
+
+
+class TransientStateError(ConflictError):
+    pass
+
+
+class PreconditionFailedError(ScalewayAPIError):
+    pass
+
+
+class ResourceExpiredError(ScalewayAPIError):
+    pass
+
+
+class OutOfStockError(ScalewayAPIError):
+    pass
+
+
+class TooManyRequestsError(ScalewayAPIError):
+    pass
+
+
+class ServerError(ScalewayAPIError):
+    pass
+
+
+ERRORS_BY_TYPE: dict[str, type[ScalewayAPIError]] = {
+    "invalid_arguments": InvalidArgumentsError,
+    "denied_authentication": DeniedAuthenticationError,
+    "permissions_denied": PermissionsDeniedError,
+    "quotas_exceeded": QuotasExceededError,
+    "not_found": ResourceNotFoundError,
+    "unknown_resource": ResourceNotFoundError,
+    "conflict": ConflictError,
+    "transient_state": TransientStateError,
+    "precondition_failed": PreconditionFailedError,
+    "resource_expired": ResourceExpiredError,
+    "out_of_stock": OutOfStockError,
+}
+
+ERRORS_BY_STATUS: dict[int, type[ScalewayAPIError]] = {
+    HTTPStatus.BAD_REQUEST: InvalidArgumentsError,
+    HTTPStatus.UNAUTHORIZED: DeniedAuthenticationError,
+    HTTPStatus.FORBIDDEN: PermissionsDeniedError,
+    HTTPStatus.NOT_FOUND: ResourceNotFoundError,
+    HTTPStatus.CONFLICT: ConflictError,
+    HTTPStatus.GONE: ResourceExpiredError,
+    HTTPStatus.PRECONDITION_FAILED: PreconditionFailedError,
+    HTTPStatus.TOO_MANY_REQUESTS: TooManyRequestsError,
+}
+
+
+def api_error(
+    method: str,
+    url: str,
+    status_code: int,
+    body: Any,
+    headers: dict[str, str] | None = None,
+) -> ScalewayAPIError:
+    error_type = body.get("type") if isinstance(body, dict) else None
+    error_class = ERRORS_BY_TYPE.get(str(error_type)) or ERRORS_BY_STATUS.get(
+        status_code,
+        ServerError
+        if status_code >= HTTPStatus.INTERNAL_SERVER_ERROR
+        else ScalewayAPIError,
+    )
+    return error_class(method, url, status_code, body, headers)

aioscaleway/_models.py

@@ -0,0 +1,30 @@
+from decimal import Decimal
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, PrivateAttr
+
+
+class ScalewayModel(BaseModel):
+    """Base of every generated model: unknown fields are kept, not rejected."""
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+        serialize_by_alias=True,
+        use_enum_values=False,
+        protected_namespaces=(),
+    )
+
+    _session: Any = PrivateAttr(default=None)
+    _key: dict[str, str | None] = PrivateAttr(default_factory=dict)
+
+
+class Money(ScalewayModel):
+    """An amount of money, as `google.type.Money`: whole units plus nanos."""
+
+    currency_code: str = ""
+    units: int = 0
+    nanos: int = 0
+
+    def to_decimal(self) -> Decimal:
+        return Decimal(self.units) + Decimal(self.nanos).scaleb(-9)

aioscaleway/_namespaces.py

@@ -0,0 +1,167 @@
+# Generated by scripts/generate.py from specs/, do not edit.
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+from aioscaleway._objects import Session
+
+if TYPE_CHECKING:
+    from aioscaleway.account import AccountNamespace
+    from aioscaleway.ai import AiNamespace
+    from aioscaleway.analytics import AnalyticsNamespace
+    from aioscaleway.billing import BillingNamespace
+    from aioscaleway.compute import ComputeNamespace
+    from aioscaleway.databases import DatabasesNamespace
+    from aioscaleway.domains import DomainsNamespace
+    from aioscaleway.email import EmailNamespace
+    from aioscaleway.iam import IamNamespace
+    from aioscaleway.iot import IotNamespace
+    from aioscaleway.kubernetes import KubernetesNamespace
+    from aioscaleway.messaging import MessagingNamespace
+    from aioscaleway.network import NetworkNamespace
+    from aioscaleway.observability import ObservabilityNamespace
+    from aioscaleway.orders import OrdersNamespace
+    from aioscaleway.serverless import ServerlessNamespace
+    from aioscaleway.storage import StorageNamespace
+    from aioscaleway.web_hosting import WebHostingNamespace
+
+
+class Namespaces:
+    """Every business area, as an attribute of the client."""
+
+    _session: Session
+
+    @cached_property
+    def account(self) -> "AccountNamespace":
+        from aioscaleway.account import (
+            AccountNamespace,  # lazy: an area is slow to import
+        )
+
+        return AccountNamespace(self._session)
+
+    @cached_property
+    def ai(self) -> "AiNamespace":
+        from aioscaleway.ai import AiNamespace  # lazy: an area is slow to import
+
+        return AiNamespace(self._session)
+
+    @cached_property
+    def analytics(self) -> "AnalyticsNamespace":
+        from aioscaleway.analytics import (
+            AnalyticsNamespace,  # lazy: an area is slow to import
+        )
+
+        return AnalyticsNamespace(self._session)
+
+    @cached_property
+    def billing(self) -> "BillingNamespace":
+        from aioscaleway.billing import (
+            BillingNamespace,  # lazy: an area is slow to import
+        )
+
+        return BillingNamespace(self._session)
+
+    @cached_property
+    def compute(self) -> "ComputeNamespace":
+        from aioscaleway.compute import (
+            ComputeNamespace,  # lazy: an area is slow to import
+        )
+
+        return ComputeNamespace(self._session)
+
+    @cached_property
+    def databases(self) -> "DatabasesNamespace":
+        from aioscaleway.databases import (
+            DatabasesNamespace,  # lazy: an area is slow to import
+        )
+
+        return DatabasesNamespace(self._session)
+
+    @cached_property
+    def domains(self) -> "DomainsNamespace":
+        from aioscaleway.domains import (
+            DomainsNamespace,  # lazy: an area is slow to import
+        )
+
+        return DomainsNamespace(self._session)
+
+    @cached_property
+    def email(self) -> "EmailNamespace":
+        from aioscaleway.email import EmailNamespace  # lazy: an area is slow to import
+
+        return EmailNamespace(self._session)
+
+    @cached_property
+    def iam(self) -> "IamNamespace":
+        from aioscaleway.iam import IamNamespace  # lazy: an area is slow to import
+
+        return IamNamespace(self._session)
+
+    @cached_property
+    def iot(self) -> "IotNamespace":
+        from aioscaleway.iot import IotNamespace  # lazy: an area is slow to import
+
+        return IotNamespace(self._session)
+
+    @cached_property
+    def kubernetes(self) -> "KubernetesNamespace":
+        from aioscaleway.kubernetes import (
+            KubernetesNamespace,  # lazy: an area is slow to import
+        )
+
+        return KubernetesNamespace(self._session)
+
+    @cached_property
+    def messaging(self) -> "MessagingNamespace":
+        from aioscaleway.messaging import (
+            MessagingNamespace,  # lazy: an area is slow to import
+        )
+
+        return MessagingNamespace(self._session)
+
+    @cached_property
+    def network(self) -> "NetworkNamespace":
+        from aioscaleway.network import (
+            NetworkNamespace,  # lazy: an area is slow to import
+        )
+
+        return NetworkNamespace(self._session)
+
+    @cached_property
+    def observability(self) -> "ObservabilityNamespace":
+        from aioscaleway.observability import (
+            ObservabilityNamespace,  # lazy: an area is slow to import
+        )
+
+        return ObservabilityNamespace(self._session)
+
+    @cached_property
+    def orders(self) -> "OrdersNamespace":
+        from aioscaleway.orders import (
+            OrdersNamespace,  # lazy: an area is slow to import
+        )
+
+        return OrdersNamespace(self._session)
+
+    @cached_property
+    def serverless(self) -> "ServerlessNamespace":
+        from aioscaleway.serverless import (
+            ServerlessNamespace,  # lazy: an area is slow to import
+        )
+
+        return ServerlessNamespace(self._session)
+
+    @cached_property
+    def storage(self) -> "StorageNamespace":
+        from aioscaleway.storage import (
+            StorageNamespace,  # lazy: an area is slow to import
+        )
+
+        return StorageNamespace(self._session)
+
+    @cached_property
+    def web_hosting(self) -> "WebHostingNamespace":
+        from aioscaleway.web_hosting import (
+            WebHostingNamespace,  # lazy: an area is slow to import
+        )
+
+        return WebHostingNamespace(self._session)