hotcodepush 0.1.0__py3-none-any.whl

hotcodepush/__init__.py

@@ -0,0 +1,183 @@
+"""The typed Python client for the HotCodePush REST API."""
+
+from ._http import UploadBody
+from ._types import NOT_GIVEN, NotGiven
+from ._upload import PART_SIZE_BYTES, SINGLE_UPLOAD_LIMIT_BYTES
+from ._version import __version__
+from .client import HotCodePush
+from .exceptions import HotCodePushError
+from .models import (
+    Account,
+    AdoptionPoint,
+    App,
+    AppFile,
+    AppUsageMonth,
+    AppUsageMonthRelation,
+    AttributeCondition,
+    Audience,
+    AudienceWarning,
+    AuditLog,
+    AuditLogRelation,
+    Binary,
+    BinaryCondition,
+    BinaryCount,
+    Bundle,
+    BundleDelta,
+    BundleDeltaRelation,
+    BundleFile,
+    BundleSignature,
+    Channel,
+    Checkout,
+    Count,
+    CreatedWebhook,
+    CustomerPortalSession,
+    DailyUpdateCounts,
+    Device,
+    DeviceCondition,
+    DeviceCount,
+    DeviceRelation,
+    EmbeddedRelease,
+    EmbeddedUser,
+    FailureAction,
+    FingerprintCondition,
+    FleetStatistics,
+    Framework,
+    HotCodePushModel,
+    Invitation,
+    InvitationRelation,
+    InvitationRole,
+    Limit,
+    ManifestFile,
+    Member,
+    MemberRelation,
+    MultipartUpload,
+    NamedEmbed,
+    Notification,
+    NotificationCategory,
+    NotificationMedium,
+    NotificationPreference,
+    NotificationRelation,
+    OidcConfig,
+    Organization,
+    OsCondition,
+    OsVersionCount,
+    Platform,
+    ReasonCount,
+    Release,
+    ReleaseAdoption,
+    ReleaseCondition,
+    ReleaseCount,
+    ReleaseCounters,
+    ReleaseDeviceEvent,
+    ReleaseProgression,
+    ReleaseRelation,
+    Role,
+    SamlConfig,
+    SigningKey,
+    SsoProvider,
+    TimeToAdoption,
+    UpdateStatistics,
+    UploadedBundlePack,
+    UploadedPart,
+    Usage,
+    UsageDay,
+    UsageMonth,
+    UsageStatistics,
+    User,
+    UserRelation,
+    Webhook,
+    WebhookDelivery,
+    WebhookEvent,
+)
+
+__all__ = [
+    "NOT_GIVEN",
+    "PART_SIZE_BYTES",
+    "SINGLE_UPLOAD_LIMIT_BYTES",
+    "Account",
+    "AdoptionPoint",
+    "App",
+    "AppFile",
+    "AppUsageMonth",
+    "AppUsageMonthRelation",
+    "AttributeCondition",
+    "Audience",
+    "AudienceWarning",
+    "AuditLog",
+    "AuditLogRelation",
+    "Binary",
+    "BinaryCondition",
+    "BinaryCount",
+    "Bundle",
+    "BundleDelta",
+    "BundleDeltaRelation",
+    "BundleFile",
+    "BundleSignature",
+    "Channel",
+    "Checkout",
+    "Count",
+    "CreatedWebhook",
+    "CustomerPortalSession",
+    "DailyUpdateCounts",
+    "Device",
+    "DeviceCondition",
+    "DeviceCount",
+    "DeviceRelation",
+    "EmbeddedRelease",
+    "EmbeddedUser",
+    "FailureAction",
+    "FingerprintCondition",
+    "FleetStatistics",
+    "Framework",
+    "HotCodePush",
+    "HotCodePushError",
+    "HotCodePushModel",
+    "Invitation",
+    "InvitationRelation",
+    "InvitationRole",
+    "Limit",
+    "ManifestFile",
+    "Member",
+    "MemberRelation",
+    "MultipartUpload",
+    "NamedEmbed",
+    "NotGiven",
+    "Notification",
+    "NotificationCategory",
+    "NotificationMedium",
+    "NotificationPreference",
+    "NotificationRelation",
+    "OidcConfig",
+    "Organization",
+    "OsCondition",
+    "OsVersionCount",
+    "Platform",
+    "ReasonCount",
+    "Release",
+    "ReleaseAdoption",
+    "ReleaseCondition",
+    "ReleaseCount",
+    "ReleaseCounters",
+    "ReleaseDeviceEvent",
+    "ReleaseProgression",
+    "ReleaseRelation",
+    "Role",
+    "SamlConfig",
+    "SigningKey",
+    "SsoProvider",
+    "TimeToAdoption",
+    "UpdateStatistics",
+    "UploadBody",
+    "UploadedBundlePack",
+    "UploadedPart",
+    "Usage",
+    "UsageDay",
+    "UsageMonth",
+    "UsageStatistics",
+    "User",
+    "UserRelation",
+    "Webhook",
+    "WebhookDelivery",
+    "WebhookEvent",
+    "__version__",
+]

hotcodepush/_http.py

@@ -0,0 +1,314 @@
+"""The one place that sends a request: the headers, the timeout, the retry, JSON in and out."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping, Sequence
+from datetime import UTC, date, datetime
+from email.utils import parsedate_to_datetime
+from time import sleep
+from typing import BinaryIO, Literal, TypeVar
+from urllib.parse import quote
+from uuid import uuid4
+
+import httpx
+from pydantic import BaseModel, TypeAdapter
+
+from ._types import NotGiven
+from ._version import __version__
+from .exceptions import resolve_hot_code_push_error
+
+COMMA_LIST_QUERY_NAMES = frozenset({"ids", "relations"})
+DEFAULT_BASE_URL = "https://api.hotcodepush.com"
+DEFAULT_CLIENT = f"python/{__version__}"
+IDEMPOTENT_METHODS = frozenset({"DELETE", "GET", "PUT"})
+INITIAL_RETRY_DELAY_SECONDS = 0.5
+JSON_TIMEOUT_SECONDS = 60.0
+MAX_ATTEMPTS = 3
+MAX_RETRY_AFTER_SECONDS = 60.0
+"""The longest wait a `Retry-After` is followed for: the API's rate limits count in sixty-second
+windows."""
+PATH_PARAMETER_PATTERN = re.compile(r"\{(\w+)\}")
+RETRY_AFTER_STATUSES = frozenset({429, 503})
+UPLOAD_TIMEOUT_SECONDS = 600.0
+"""Ten minutes per attempt: the single-upload limit at about a hundred kilobytes a second."""
+
+HttpMethod = Literal["DELETE", "GET", "PATCH", "POST", "PUT"]
+JsonBody = Mapping[str, object]
+Query = Mapping[str, bool | date | datetime | int | str | Sequence[str] | NotGiven]
+UploadBody = bytes | BinaryIO
+"""Bytes, read again when a retry needs them, or a file object, read once and never retried."""
+
+T = TypeVar("T")
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        client: str,
+        http_client: httpx.Client | None,
+        timeout: float | None,
+        token: str | None,
+        user_agent: str | None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._headers = resolve_headers(client=client, token=token, user_agent=user_agent)
+        self._httpx_client = http_client or httpx.Client()
+        self._is_httpx_client_owned = http_client is None
+        self._json_timeout_seconds = JSON_TIMEOUT_SECONDS if timeout is None else timeout
+
+    def close(self) -> None:
+        """Closes the connection pool, unless the caller passed its own `http_client`."""
+        if self._is_httpx_client_owned:
+            self._httpx_client.close()
+
+    def fetch_bytes(self, method: HttpMethod, path: str, *, query: Query | None = None) -> bytes:
+        """A request answered with a binary body, such as a CSV download or a channel's QR image,
+        read whole.
+        """
+        return self._fetch_response(method, path, query=query).content
+
+    def fetch_creating_post(
+        self,
+        path: str,
+        response_type: type[T],
+        *,
+        body: JsonBody,
+        idempotency_key: str | NotGiven,
+    ) -> T:
+        """A creating `POST`, sent with an `Idempotency-Key`: the caller's, or one generated
+        for this call and kept across its retries, which the API answers with the first result.
+        """
+        resolved_idempotency_key = (
+            str(uuid4()) if isinstance(idempotency_key, NotGiven) else idempotency_key
+        )
+        return self.fetch_json(
+            "POST",
+            path,
+            response_type,
+            body=body,
+            headers={"Idempotency-Key": resolved_idempotency_key},
+            is_retryable=True,
+        )
+
+    def fetch_json(
+        self,
+        method: HttpMethod,
+        path: str,
+        response_type: type[T],
+        *,
+        body: JsonBody | None = None,
+        headers: Mapping[str, str] | None = None,
+        is_retryable: bool | None = None,
+        query: Query | None = None,
+    ) -> T:
+        """A request answered with JSON, validated into `response_type`.
+
+        `is_retryable` defaults to true for `DELETE`, `GET` and `PUT`, false for `PATCH` and
+        `POST`; a `POST` sets it where the API makes a repeat safe, through a stored idempotency
+        key or a transition that answers a repeat unchanged.
+        """
+        response = self._fetch_response(
+            method, path, body=body, headers=headers, is_retryable=is_retryable, query=query
+        )
+        return TypeAdapter(response_type).validate_json(response.content)
+
+    def fetch_status(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        body: JsonBody | None = None,
+        is_retryable: bool | None = None,
+        query: Query | None = None,
+    ) -> None:
+        """A request whose status is the whole answer: the body, such as `/health`'s
+        plain-text `ok`, is discarded. `is_retryable` defaults as `fetch_json`'s does.
+        """
+        self._fetch_response(method, path, body=body, is_retryable=is_retryable, query=query)
+
+    def fetch_upload(
+        self,
+        path: str,
+        response_type: type[T],
+        *,
+        body: UploadBody,
+        content_length: int | None,
+        content_type: str,
+    ) -> T:
+        """A binary `PUT`, streamed as it is read; a file object is read once, so only bytes
+        are retried.
+        """
+        request = self._httpx_client.build_request(
+            "PUT",
+            self._base_url + path,
+            content=body,
+            headers={
+                **self._headers,
+                "Content-Length": str(resolve_content_length(body, content_length)),
+                "Content-Type": content_type,
+            },
+            timeout=UPLOAD_TIMEOUT_SECONDS,
+        )
+        response = self._send(request, is_retryable=isinstance(body, bytes))
+        return TypeAdapter(response_type).validate_json(response.content)
+
+    def _fetch_response(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        body: JsonBody | None = None,
+        headers: Mapping[str, str] | None = None,
+        is_retryable: bool | None = None,
+        query: Query | None = None,
+    ) -> httpx.Response:
+        request = self._httpx_client.build_request(
+            method,
+            self._base_url + path,
+            headers={**self._headers, **(headers or {})},
+            json=None if body is None else resolve_json_body(body),
+            params=resolve_query_params(query or {}),
+            timeout=self._json_timeout_seconds,
+        )
+        return self._send(
+            request,
+            is_retryable=method in IDEMPOTENT_METHODS if is_retryable is None else is_retryable,
+        )
+
+    def _send(self, request: httpx.Request, *, is_retryable: bool) -> httpx.Response:
+        def send() -> httpx.Response:
+            return self._httpx_client.send(request)
+
+        response = send_with_retry(send) if is_retryable else send()
+        if not response.is_success:
+            raise resolve_hot_code_push_error(response.status_code, response.text)
+        return response
+
+
+def is_retryable_status(status: int) -> bool:
+    return status in (408, 429) or status >= 500
+
+
+def resolve_content_length(body: UploadBody, content_length: int | None) -> int:
+    if isinstance(body, bytes):
+        return len(body)
+    if content_length is None:
+        raise ValueError("A file object body needs its content_length.")
+    return content_length
+
+
+def resolve_headers(*, client: str, token: str | None, user_agent: str | None) -> dict[str, str]:
+    headers = {"Accept": "application/json", "X-HotCodePush-Client": client}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    if user_agent:
+        headers["User-Agent"] = user_agent
+    return headers
+
+
+def resolve_json_body(body: JsonBody) -> dict[str, object]:
+    """The body without its `NOT_GIVEN` values, models by their API names without their `None`
+    fields, since no nested field of the API takes `null`, and timestamps in UTC.
+    """
+    return {
+        name: resolve_json_value(value)
+        for name, value in body.items()
+        if not isinstance(value, NotGiven)
+    }
+
+
+def resolve_json_value(value: object) -> object:
+    if isinstance(value, BaseModel):
+        return value.model_dump(by_alias=True, exclude_none=True, mode="json")
+    if isinstance(value, datetime):
+        return resolve_utc_timestamp(value)
+    if isinstance(value, list):
+        return [resolve_json_value(item) for item in value]
+    return value
+
+
+def resolve_path(template: str, **parameters: int | str) -> str:
+    """Fills a path template of the OpenAPI snapshot, `/v1/apps/{appId}`, with its encoded
+    parameters.
+    """
+
+    def resolve_parameter(match: re.Match[str]) -> str:
+        name = match.group(1)
+        if name not in parameters:
+            raise ValueError(f"The path parameter {name} of {template} is missing.")
+        return quote(str(parameters[name]), safe="")
+
+    return PATH_PARAMETER_PATTERN.sub(resolve_parameter, template)
+
+
+def resolve_query_params(query: Query) -> tuple[tuple[str, str], ...]:
+    """The query as name and value pairs: `NOT_GIVEN`, empty strings and empty lists are left
+    out; `ids` and `relations` are the API's comma lists, and every other list repeats its
+    parameter, `?binary=…&binary=…`, since its values may hold a comma.
+    """
+    params: list[tuple[str, str]] = []
+    for name, value in query.items():
+        if isinstance(value, NotGiven) or value == "" or value == []:
+            continue
+        if isinstance(value, list):
+            values = [",".join(value)] if name in COMMA_LIST_QUERY_NAMES else value
+            params.extend((name, item) for item in values)
+        elif isinstance(value, bool):
+            params.append((name, "true" if value else "false"))
+        elif isinstance(value, datetime):
+            params.append((name, resolve_utc_timestamp(value)))
+        else:
+            params.append((name, str(value)))
+    return tuple(params)
+
+
+def resolve_retry_after_seconds(response: httpx.Response) -> float | None:
+    """The wait a 429 or a 503 asks for in `Retry-After`, delay seconds or an HTTP date, capped
+    at `MAX_RETRY_AFTER_SECONDS`; None for any other status, a missing header or one that does
+    not parse.
+    """
+    retry_after = response.headers.get("Retry-After", "").strip()
+    if response.status_code not in RETRY_AFTER_STATUSES or not retry_after:
+        return None
+    if retry_after.isdigit():
+        retry_after_seconds = float(retry_after)
+    else:
+        try:
+            retry_at = parsedate_to_datetime(retry_after)
+        except ValueError:
+            return None
+        retry_after_seconds = (retry_at - datetime.now(UTC)).total_seconds()
+    return min(max(retry_after_seconds, 0.0), MAX_RETRY_AFTER_SECONDS)
+
+
+def resolve_utc_timestamp(value: datetime) -> str:
+    """ISO 8601 in UTC with a `Z`, the only offset the API accepts."""
+    return value.astimezone(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def send_with_retry(send: Callable[[], httpx.Response]) -> httpx.Response:
+    """Sends up to `MAX_ATTEMPTS` times on a transport error, 408, 429 and 5xx, backing off
+    exponentially from `INITIAL_RETRY_DELAY_SECONDS`, or waiting a 429's or a 503's
+    `Retry-After`; the last attempt's response or error is the call's.
+    """
+    attempt = 1
+    while True:
+        is_last_attempt = attempt == MAX_ATTEMPTS
+        retry_after_seconds = None
+        try:
+            response = send()
+        except httpx.TransportError:
+            if is_last_attempt:
+                raise
+        else:
+            if is_last_attempt or not is_retryable_status(response.status_code):
+                return response
+            response.close()
+            retry_after_seconds = resolve_retry_after_seconds(response)
+        if retry_after_seconds is None:
+            retry_after_seconds = INITIAL_RETRY_DELAY_SECONDS * 2 ** (attempt - 1)
+        sleep(retry_after_seconds)
+        attempt += 1

hotcodepush/_types.py

@@ -0,0 +1,15 @@
+"""The sentinel of an optional argument the request leaves out."""
+
+
+class NotGiven:
+    """The type of `NOT_GIVEN`, the default of every optional argument.
+
+    An argument left at `NOT_GIVEN` stays out of the request; `None` sends JSON `null`
+    where the API takes one, such as clearing a channel's `expires_at`.
+    """
+
+    def __repr__(self) -> str:
+        return "NOT_GIVEN"
+
+
+NOT_GIVEN = NotGiven()

hotcodepush/_upload.py

@@ -0,0 +1,51 @@
+"""The single-or-parts rule of an upload: bytes above the single-upload limit go up in parts."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from contextlib import suppress
+from typing import TypeGuard, TypeVar
+
+from ._http import UploadBody
+from .models import MultipartUpload, UploadedPart
+
+PART_SIZE_BYTES = 10 * 1024 * 1024
+"""Every part but the last is this size: at least five mebibytes and all of one size, the bucket's
+rule."""
+SINGLE_UPLOAD_LIMIT_BYTES = 64 * 1024 * 1024
+"""Bytes go up in one request up to this size and in parts above it, well under the request-body
+cap of the API's plan."""
+
+T = TypeVar("T")
+
+
+def is_above_single_upload_limit(body: UploadBody) -> TypeGuard[bytes]:
+    """A file object is read once and cannot be split, so only bytes go up in parts."""
+    return isinstance(body, bytes) and len(body) > SINGLE_UPLOAD_LIMIT_BYTES
+
+
+def upload_in_parts(
+    body: bytes,
+    *,
+    complete: Callable[[str, list[UploadedPart]], T],
+    create: Callable[[], MultipartUpload],
+    delete: Callable[[str], None],
+    upload_part: Callable[[str, int, bytes], UploadedPart],
+) -> T:
+    """Uploads bytes in parts of `PART_SIZE_BYTES`, numbered from 1, then completes the upload;
+    a failed part or completion deletes the upload and re-raises.
+
+    Each callable is one call of the multipart upload the files and the pack share, bound to the
+    path parameters of its target.
+    """
+    upload_id = create().upload_id
+    try:
+        uploaded_parts = [
+            upload_part(upload_id, part_number, body[start : start + PART_SIZE_BYTES])
+            for part_number, start in enumerate(range(0, len(body), PART_SIZE_BYTES), start=1)
+        ]
+        return complete(upload_id, uploaded_parts)
+    except Exception:
+        with suppress(Exception):
+            delete(upload_id)
+        raise

hotcodepush/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"  # x-release-please-version

hotcodepush/client.py

@@ -0,0 +1,81 @@
+"""The client for the HotCodePush REST API."""
+
+from __future__ import annotations
+
+import os
+from types import TracebackType
+
+import httpx
+
+from ._http import DEFAULT_BASE_URL, DEFAULT_CLIENT, HttpClient
+from .resources.apps import AppsResource
+from .resources.health import HealthResource
+from .resources.invitations import InvitationsResource
+from .resources.notification_preferences import NotificationPreferencesResource
+from .resources.notifications import NotificationsResource
+from .resources.organizations import OrganizationsResource
+from .resources.users import UsersResource
+
+TOKEN_ENVIRONMENT_VARIABLE = "HOTCODEPUSH_TOKEN"
+
+
+class HotCodePush:
+    """The client for the HotCodePush REST API.
+
+    Resources mirror the paths: `/v1/organizations/{organizationId}/apps` is
+    `organizations.apps`, `/v1/apps/{appId}/channels` is `apps.channels`.
+
+    Args:
+        token: The API token, sent as `Authorization: Bearer <token>`; falls back to the
+            `HOTCODEPUSH_TOKEN` environment variable and stays optional, since `/health` needs
+            none.
+        base_url: The base URL of the API.
+        client: The `X-HotCodePush-Client` header, `<name>/<version>`.
+        http_client: The `httpx.Client` that sends the requests in place of the client's own;
+            `close` leaves it open.
+        timeout: The seconds every phase of a JSON call's attempt may take, httpx's connect,
+            read, write and pool timeouts; sixty when unset. An upload attempt gets ten minutes.
+        user_agent: The `User-Agent` header, sent only when set, since a session keeps it and
+            the sessions page names the client by it.
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        client: str = DEFAULT_CLIENT,
+        http_client: httpx.Client | None = None,
+        timeout: float | None = None,
+        user_agent: str | None = None,
+    ) -> None:
+        self._http_client = HttpClient(
+            base_url=base_url,
+            client=client,
+            http_client=http_client,
+            timeout=timeout,
+            token=token or os.environ.get(TOKEN_ENVIRONMENT_VARIABLE),
+            user_agent=user_agent,
+        )
+        self.apps = AppsResource(self._http_client)
+        self.health = HealthResource(self._http_client)
+        self.invitations = InvitationsResource(self._http_client)
+        self.notification_preferences = NotificationPreferencesResource(self._http_client)
+        self.notifications = NotificationsResource(self._http_client)
+        self.organizations = OrganizationsResource(self._http_client)
+        self.users = UsersResource(self._http_client)
+
+    def close(self) -> None:
+        """Closes the connection pool, unless the requests go through the caller's `http_client`."""
+        self._http_client.close()
+
+    def __enter__(self) -> HotCodePush:
+        return self
+
+    def __exit__(
+        self,
+        exception_type: type[BaseException] | None,
+        exception: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()

hotcodepush/exceptions.py

@@ -0,0 +1,45 @@
+"""The error raised for an API answer outside 2xx."""
+
+from __future__ import annotations
+
+import json
+
+
+class HotCodePushError(Exception):
+    """Raised when the API answers with a status outside 2xx.
+
+    `code`, `message` and `details` are the API's, verbatim, from its one error shape;
+    a response outside that shape, such as a page of the platform in front of the API,
+    is `E_UNEXPECTED_RESPONSE` with the status, its body left out.
+    """
+
+    def __init__(self, *, code: str, details: object, message: str, status: int) -> None:
+        super().__init__(message)
+        self.code = code
+        self.details = details
+        self.message = message
+        self.status = status
+
+
+def resolve_hot_code_push_error(status: int, text: str) -> HotCodePushError:
+    body = resolve_json_object(text)
+    code, message = body.get("code"), body.get("message")
+    if isinstance(code, str) and isinstance(message, str):
+        return HotCodePushError(
+            code=code, details=body.get("details"), message=message, status=status
+        )
+    return HotCodePushError(
+        code="E_UNEXPECTED_RESPONSE",
+        details=None,
+        message=f"Request failed with status {status}.",
+        status=status,
+    )
+
+
+def resolve_json_object(text: str) -> dict[str, object]:
+    """The JSON object the text holds; empty when it holds none, such as an HTML page."""
+    try:
+        body: object = json.loads(text)
+    except ValueError:
+        return {}
+    return body if isinstance(body, dict) else {}