hotcodepush 0.2.0__tar.gz → 0.2.1__tar.gz

{hotcodepush-0.2.0 → hotcodepush-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hotcodepush
-Version: 0.2.0
+Version: 0.2.1
 Summary: The typed Python client for the HotCodePush REST API
 Project-URL: Homepage, https://hotcodepush.com
 Project-URL: Documentation, https://hotcodepush.com/docs/api/python
@@ -34,13 +34,7 @@ The typed Python client for the [HotCodePush](https://hotcodepush.com) REST API,
 ## Installation
 
 ```sh
-pip install hotcodepush
-```
-
-Or with uv:
-
-```sh
-uv add hotcodepush
+pip install hotcodepush    # or: uv add hotcodepush
 ```
 
 It requires Python 3.11 or later.
@@ -61,33 +55,27 @@ hot_code_push.apps.channels.pause(app_id=app.id, channel_id=channel.id)
 ```
 
 The resources mirror the API's paths, `/v1/apps/{appId}/channels` being `apps.channels`.
-Every method takes keyword arguments and returns pydantic models with snake_case fields.
-An optional argument you leave out stays out of the request; `None` sends `null`, which clears a field such as a channel's `expires_at`.
-`users.get(user_id="me")` answers the caller behind the token, as `me` addresses the caller wherever the API takes a `{userId}`.
-
-An upload takes `bytes` or a file object with its `content_length`, and streams it.
-Bytes above 64 MiB go up in parts, and a retry sends them again; a file object is read once, so a failed upload of one is not retried.
-
-Creating an organization, an invitation, an app, a channel, a release, a rollback, a bundle or a binary sends an `Idempotency-Key`, a UUID per call kept across the client's own retries; pass `idempotency_key` to reuse one when you retry the call yourself, and the API answers the first result again for 24 hours.
-
-A failed request raises a `HotCodePushError` with the API's `code`, `message` and `details` and the HTTP `status`.
+Every method takes keyword arguments and returns pydantic models with snake_case fields; an argument left out stays out of the request, and `None` sends `null`.
+Uploads take `bytes` or a file object with its `content_length` and stream it.
+Creating calls send an `Idempotency-Key` and are retried; pass `idempotency_key` to reuse one across your own retries.
+A failed request raises a `HotCodePushError` with the API's `code`, `message`, `details` and the HTTP `status`.
 
 ## Documentation
 
-The documentation lives at [hotcodepush.com/docs/api/python](https://hotcodepush.com/docs/api/python).
+See [hotcodepush.com/docs/api/python](https://hotcodepush.com/docs/api/python).
 
 ## Development
 
 ```sh
 uv sync
-uv run ruff format --check .
-uv run ruff check .
-uv run mypy
 uv run pytest
+uv run ruff check . && uv run mypy
+uv run ruff format .       # run before every commit
 uv build
 ```
 
-`uv run ruff format .` formats the code.
+`uv run scripts/sync_openapi.py` fetches the API's OpenAPI document into `openapi.json`, which the contract test checks the client against.
+`CLAUDE.md` holds the layout and the rules.
 
 ## License
 

hotcodepush-0.2.1/README.md

@@ -0,0 +1,55 @@
+# hotcodepush
+
+[![PyPI](https://img.shields.io/pypi/v/hotcodepush)](https://pypi.org/project/hotcodepush/)
+
+The typed Python client for the [HotCodePush](https://hotcodepush.com) REST API, the over-the-air (OTA) update platform for React Native, Expo, Capacitor and Cordova.
+
+## Installation
+
+```sh
+pip install hotcodepush    # or: uv add hotcodepush
+```
+
+It requires Python 3.11 or later.
+
+## Usage
+
+```python
+from hotcodepush import HotCodePush
+
+hot_code_push = HotCodePush()  # reads the API token from HOTCODEPUSH_TOKEN
+
+organization, *_ = hot_code_push.organizations.list()
+app = hot_code_push.organizations.apps.create(
+    framework="capacitor", name="Demo", organization_id=organization.id
+)
+channel = hot_code_push.apps.channels.create(app_id=app.id, name="staging")
+hot_code_push.apps.channels.pause(app_id=app.id, channel_id=channel.id)
+```
+
+The resources mirror the API's paths, `/v1/apps/{appId}/channels` being `apps.channels`.
+Every method takes keyword arguments and returns pydantic models with snake_case fields; an argument left out stays out of the request, and `None` sends `null`.
+Uploads take `bytes` or a file object with its `content_length` and stream it.
+Creating calls send an `Idempotency-Key` and are retried; pass `idempotency_key` to reuse one across your own retries.
+A failed request raises a `HotCodePushError` with the API's `code`, `message`, `details` and the HTTP `status`.
+
+## Documentation
+
+See [hotcodepush.com/docs/api/python](https://hotcodepush.com/docs/api/python).
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+uv run ruff check . && uv run mypy
+uv run ruff format .       # run before every commit
+uv build
+```
+
+`uv run scripts/sync_openapi.py` fetches the API's OpenAPI document into `openapi.json`, which the contract test checks the client against.
+`CLAUDE.md` holds the layout and the rules.
+
+## License
+
+See [LICENSE](./LICENSE).

{hotcodepush-0.2.0 → hotcodepush-0.2.1}/src/hotcodepush/_http.py

@@ -1,5 +1,3 @@
-"""The one place that sends a request: the headers, the timeout, the retry, JSON in and out."""
-
 from __future__ import annotations
 
 import re
@@ -25,19 +23,19 @@ IDEMPOTENT_METHODS = frozenset({"DELETE", "GET", "PUT"})
 INITIAL_RETRY_DELAY_SECONDS = 0.5
 JSON_TIMEOUT_SECONDS = 60.0
 MAX_ATTEMPTS = 3
+# The API counts its rate limits in sixty-second windows.
 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})
+# Enough for the single-upload limit at about 100 kB a second.
 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."""
+"""The body of an upload: bytes, which a failed attempt sends again, or a file object, read once
+and never retried."""
 
 T = TypeVar("T")
 
@@ -60,14 +58,10 @@ class HttpClient:
         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(
@@ -78,12 +72,10 @@ class HttpClient:
         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
         )
+        # The API answers a repeated key with the first result, so a retry is safe.
         return self.fetch_json(
             "POST",
             path,
@@ -104,12 +96,6 @@ class HttpClient:
         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
         )
@@ -124,9 +110,6 @@ class HttpClient:
         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(
@@ -138,9 +121,6 @@ class HttpClient:
         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,
@@ -210,9 +190,6 @@ def resolve_headers(*, client: str, token: str | None, user_agent: str | None) -
 
 
 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()
@@ -222,6 +199,7 @@ def resolve_json_body(body: JsonBody) -> dict[str, object]:
 
 def resolve_json_value(value: object) -> object:
     if isinstance(value, BaseModel):
+        # No nested field of the API takes `null`.
         return value.model_dump(by_alias=True, exclude_none=True, mode="json")
     if isinstance(value, datetime):
         return resolve_utc_timestamp(value)
@@ -231,10 +209,6 @@ def resolve_json_value(value: object) -> object:
 
 
 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:
@@ -245,15 +219,12 @@ def resolve_path(template: str, **parameters: int | str) -> str:
 
 
 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):
+            # Other lists repeat their parameter, since their values may hold a comma.
             values = [",".join(value)] if name in COMMA_LIST_QUERY_NAMES else value
             params.extend((name, item) for item in values)
         elif isinstance(value, bool):
@@ -266,10 +237,6 @@ def resolve_query_params(query: Query) -> tuple[tuple[str, str], ...]:
 
 
 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
@@ -285,15 +252,11 @@ def resolve_retry_after_seconds(response: httpx.Response) -> float | None:
 
 
 def resolve_utc_timestamp(value: datetime) -> str:
-    """ISO 8601 in UTC with a `Z`, the only offset the API accepts."""
+    # The API accepts only the `Z` offset.
     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

hotcodepush-0.2.1/src/hotcodepush/_types.py

@@ -0,0 +1,12 @@
+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 it, for example to clear a channel's `expires_at`.
+    """
+
+    def __repr__(self) -> str:
+        return "NOT_GIVEN"
+
+
+NOT_GIVEN = NotGiven()

{hotcodepush-0.2.0 → hotcodepush-0.2.1}/src/hotcodepush/_upload.py

@@ -1,5 +1,3 @@
-"""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
@@ -10,17 +8,16 @@ 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."""
+"""The size of every part but the last. The bucket needs parts of one size, at least 5 MiB."""
 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."""
+"""The largest bytes body sent in one request; a larger one goes up in parts. It stays well under
+the API's request body limit."""
 
 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."""
+    # A file object is read once and cannot be split.
     return isinstance(body, bytes) and len(body) > SINGLE_UPLOAD_LIMIT_BYTES
 
 
@@ -32,12 +29,6 @@ def upload_in_parts(
     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 = [

hotcodepush-0.2.1/src/hotcodepush/_version.py

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

{hotcodepush-0.2.0 → hotcodepush-0.2.1}/src/hotcodepush/client.py

@@ -1,5 +1,3 @@
-"""The client for the HotCodePush REST API."""
-
 from __future__ import annotations
 
 import os
@@ -23,20 +21,18 @@ 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`.
+    `organizations.apps`, and `/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.
+        token: The API token, sent as `Authorization: Bearer <token>`. Falls back to the
+            `HOTCODEPUSH_TOKEN` environment variable. 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.
+        http_client: An `httpx.Client` to send the requests with. `close` leaves it open.
+        timeout: The seconds each phase of a JSON request attempt may take: connect, read,
+            write and pool. Sixty when unset. An upload attempt always gets ten minutes.
+        user_agent: The `User-Agent` header, sent only when set. A session stores it, and the
+            sessions page names the client by it.
     """
 
     def __init__(
@@ -66,7 +62,7 @@ class HotCodePush:
         self.users = UsersResource(self._http_client)
 
     def close(self) -> None:
-        """Closes the connection pool, unless the requests go through the caller's `http_client`."""
+        """Closes the connection pool, unless the caller passed its own `http_client`."""
         self._http_client.close()
 
     def __enter__(self) -> HotCodePush:

{hotcodepush-0.2.0 → hotcodepush-0.2.1}/src/hotcodepush/exceptions.py

@@ -1,5 +1,3 @@
-"""The error raised for an API answer outside 2xx."""
-
 from __future__ import annotations
 
 import json
@@ -8,9 +6,9 @@ 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 `unexpected_response` with the status, its body left out.
+    `code`, `message` and `details` come verbatim from the API's error body. A response without
+    that shape, such as a page from a proxy in front of the API, raises `unexpected_response` with
+    the status and without the body.
     """
 
     def __init__(self, *, code: str, details: object, message: str, status: int) -> None:
@@ -37,7 +35,6 @@ def resolve_hot_code_push_error(status: int, text: str) -> HotCodePushError:
 
 
 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: