vertracloud-api 0.2.0__tar.gz → 0.2.2__tar.gz

vertracloud_api-0.2.2/.release-please-manifest.json

@@ -0,0 +1 @@
+{".":"0.2.2"}

{vertracloud_api-0.2.0 → vertracloud_api-0.2.2}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.2.2](https://github.com/vertracloud/sdk-api-py/compare/v0.2.1...v0.2.2) (2026-10-18)
+
+
+### Bug Fixes
+
+* support async app creation (building status, wait_until_ready) ([044a73f](https://github.com/vertracloud/sdk-api-py/commit/044a73f981f540e1e070d52c0243469448243e46))
+
+## [0.2.1](https://github.com/vertracloud/sdk-api-py/compare/v0.2.0...v0.2.1) (2026-10-15)
+
+
+### Features
+
+* **blob:** add rename_on_conflict to put and copy ([6773c4c](https://github.com/vertracloud/sdk-api-py/commit/6773c4cfa63032875dfe1b3f92967fe3128b4e7c))
+
 ## [0.2.0](https://github.com/vertracloud/sdk-api-py/compare/v0.1.5...v0.2.0) (2026-10-15)
 
 

{vertracloud_api-0.2.0 → vertracloud_api-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vertracloud-api
-Version: 0.2.0
+Version: 0.2.2
 Summary: Official Python SDK for the public API of Vertra Cloud, a Brazilian application hosting platform (PaaS).
 Project-URL: Homepage, https://vertracloud.app
 Project-URL: Documentation, https://docs.vertracloud.app/sdks
@@ -142,6 +142,23 @@ with open("backup.zip", "wb") as f:
 
 `client.snapshots.download` works the same way.
 
+### Waiting for the first build
+
+`apps.create` replies right away with `status: "building"`. Wait for the build to end:
+
+```python
+app = client.apps.create({"name": "my-app", "memory": 512}, file=data)
+try:
+    app = client.apps.wait_until_ready(app["id"], timeout=600, interval=2)  # status is "up"
+# ended "down": e.code is app["last_build_error"] (e.g. "INSTALL_OUT_OF_MEMORY"), "APP_DOWN" if none
+except vertracloud.AppBuildFailedError as e:
+    print(client.apps.logs(app["id"]))
+except vertracloud.WaitTimeoutError:  # still building after `timeout` seconds
+    ...
+```
+
+`missing_dependencies` on the app is filled only after the build ends. Before it ends, calls that need a stopped or running app can fail with `APP_BUILDING` (409).
+
 ### Realtime logs (SSE)
 
 ```python

{vertracloud_api-0.2.0 → vertracloud_api-0.2.2}/README.md

@@ -123,6 +123,23 @@ with open("backup.zip", "wb") as f:
 
 `client.snapshots.download` works the same way.
 
+### Waiting for the first build
+
+`apps.create` replies right away with `status: "building"`. Wait for the build to end:
+
+```python
+app = client.apps.create({"name": "my-app", "memory": 512}, file=data)
+try:
+    app = client.apps.wait_until_ready(app["id"], timeout=600, interval=2)  # status is "up"
+# ended "down": e.code is app["last_build_error"] (e.g. "INSTALL_OUT_OF_MEMORY"), "APP_DOWN" if none
+except vertracloud.AppBuildFailedError as e:
+    print(client.apps.logs(app["id"]))
+except vertracloud.WaitTimeoutError:  # still building after `timeout` seconds
+    ...
+```
+
+`missing_dependencies` on the app is filled only after the build ends. Before it ends, calls that need a stopped or running app can fail with `APP_BUILDING` (409).
+
 ### Realtime logs (SSE)
 
 ```python

{vertracloud_api-0.2.0 → vertracloud_api-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vertracloud-api"
-version = "0.2.0"
+version = "0.2.2"
 description = "Official Python SDK for the public API of Vertra Cloud, a Brazilian application hosting platform (PaaS)."
 readme = "README.md"
 license = "MIT"

{vertracloud_api-0.2.0 → vertracloud_api-0.2.2}/src/vertracloud/__init__.py

@@ -2,12 +2,15 @@
 
 from .client import VertraClient, __version__
 from .errors import (
+    AppBuildFailedError,
+    AppNotReadyError,
     AuthenticationError,
     NotFoundError,
     RateLimitError,
     ScopeDeniedError,
     ValidationError,
     VertraAPIError,
+    WaitTimeoutError,
 )
 from .sse import SseEvent, SseStream
 from .transport import Response, Transport, UrllibTransport
@@ -16,6 +19,9 @@ __all__ = [
     "VertraClient",
     "__version__",
     "VertraAPIError",
+    "AppNotReadyError",
+    "AppBuildFailedError",
+    "WaitTimeoutError",
     "AuthenticationError",
     "ScopeDeniedError",
     "NotFoundError",

{vertracloud_api-0.2.0 → vertracloud_api-0.2.2}/src/vertracloud/client.py

@@ -16,7 +16,7 @@ from .sse import SseStream
 from .transport import Response, Transport, UrllibTransport
 from .types import JsonValue
 
-__version__ = "0.2.0"  # x-release-please-version
+__version__ = "0.2.2"  # x-release-please-version
 
 DEFAULT_BASE_URL = "https://api.vertracloud.app"
 DEFAULT_BLOB_BASE_URL = "https://blob.vertracloud.app/v1"

{vertracloud_api-0.2.0 → vertracloud_api-0.2.2}/src/vertracloud/errors.py

@@ -70,6 +70,25 @@ class RateLimitError(VertraAPIError):
         )
 
 
+class AppNotReadyError(Exception):
+    """`apps.wait_until_ready` ended without a running app. `app` is the last payload seen
+    (`None` on timeout before any reply). The cause of a `down` build is in `apps.logs`."""
+
+    def __init__(self, message: str, *, code: str, app: Any = None) -> None:
+        self.code = code
+        self.app = app
+        super().__init__(f"{code}: {message}")
+
+
+class AppBuildFailedError(AppNotReadyError):
+    """The build ended with the app `down`. `code` is the app's `last_build_error` (e.g.
+    `INSTALL_OUT_OF_MEMORY`), or `APP_DOWN` when the API sent none."""
+
+
+class WaitTimeoutError(AppNotReadyError):
+    """`wait_until_ready` timed out while the app was still `building` (`code` is `WAIT_TIMEOUT`)."""
+
+
 def error_from_response(status: int, body: dict[str, Any]) -> VertraAPIError:
     """Picks the class from the HTTP status; `code` comes from the error response body."""
     code = str(body.get("code") or "UNKNOWN_ERROR")

{vertracloud_api-0.2.0 → vertracloud_api-0.2.2}/src/vertracloud/resources/apps.py

@@ -5,9 +5,11 @@
 
 from __future__ import annotations
 
+import time
 from typing import TYPE_CHECKING, Any
 
 from ..client import LARGE_PAYLOAD_TIMEOUT, MultipartField, encode_path_param
+from ..errors import AppBuildFailedError, WaitTimeoutError
 from ..sse import SseStream
 from ..types import (
     APIAppFileUploadResponse,
@@ -442,7 +444,8 @@ class AppsResource:
     ) -> APIApplication:
         """POST /v1/apps — scope `apps:write`. Multipart: field `file` (zip) OR `snapshot_id`
         in `body`, other fields as text parts. Rate limit 15/min, plus the plan's
-        deploys-per-hour cap.
+        deploys-per-hour cap. Replies 202 with `status: "building"`: the build continues in the
+        background — use `wait_until_ready`, `logs` or `realtime` to follow it.
         Doc: https://docs.vertracloud.app/api-reference/endpoint/apps/create
         """
         fields: list[MultipartField] = []
@@ -463,6 +466,32 @@ class AppsResource:
             "POST", "/v1/apps", fields=fields, timeout=timeout if timeout is not None else LARGE_PAYLOAD_TIMEOUT
         )
 
+    def wait_until_ready(
+        self,
+        app_id: str,
+        *,
+        timeout: float = 600.0,
+        interval: float = 2.0,
+        workspace_id: str | None = None,
+    ) -> APIApplication:
+        """Polls `GET /v1/apps/:id` while `status` is `building`. Returns the app when it is `up`;
+        raises `AppBuildFailedError` when it ends `down` and `WaitTimeoutError` after `timeout`
+        seconds. API errors from the polling propagate unchanged."""
+        deadline = time.monotonic() + timeout
+        while True:
+            app = self.get(app_id, workspace_id=workspace_id)
+            if app["status"] == "up":
+                return app
+            if app["status"] == "down":
+                raise AppBuildFailedError(
+                    "the build ended and the app is down; read apps.logs for the cause",
+                    code=app.get("last_build_error") or "APP_DOWN",
+                    app=app,
+                )
+            if time.monotonic() + interval > deadline:
+                raise WaitTimeoutError(f"still building after {timeout:g}s", code="WAIT_TIMEOUT", app=app)
+            time.sleep(interval)
+
     def start(self, app_id: str, *, workspace_id: str | None = None) -> APIApplicationOperationResponse:
         """POST /v1/apps/:id/start — scope `apps:write`."""
         return self._c.request_json(

{vertracloud_api-0.2.0 → vertracloud_api-0.2.2}/src/vertracloud/resources/blob.py

@@ -240,6 +240,7 @@ class BlobResource:
         visibility: BlobVisibility | None = None,
         overwrite: bool | None = None,
         random_suffix: bool | None = None,
+        rename_on_conflict: bool | None = None,
         cache_control: str | None = None,
         content_disposition: str | None = None,
         filename: str | None = None,
@@ -253,11 +254,14 @@ class BlobResource:
         Up to 5 MB: `POST /objects` (multipart). Larger: `POST /uploads`, then a presigned
         PUT (single) or parts (multipart) and `/complete`. `on_progress(loaded, total)` is
         called as bytes are sent. If a large upload is interrupted, call `resume`.
+        `rename_on_conflict=True` saves a taken path as `name-1.ext`, `name-2.ext`, … (not with `overwrite`);
+        the returned object has the final path.
         """
         opts: dict[str, Any] = {
             "visibility": visibility,
             "overwrite": overwrite,
             "random_suffix": random_suffix,
+            "rename_on_conflict": rename_on_conflict,
             "cache_control": cache_control,
             "content_disposition": content_disposition,
             "filename": filename,
@@ -428,7 +432,10 @@ class BlobResource:
         return results
 
     def copy(self, id: str, path: str, *, workspace_id: str | None = None, **opts: Any) -> APIBlobObject:
-        """POST /objects/copy — `overwrite`, `random_suffix`, `visibility`, `move` as options."""
+        """POST /objects/copy — `overwrite`, `random_suffix`, `visibility`, `move` as options.
+
+        `rename_on_conflict=True` (copy only) saves a taken path, even the source's own, as `name-1.ext`.
+        """
         return self._json(
             "POST", "/objects/copy", json_body={"source": id, "path": path, **opts}, query=_ws(workspace_id)
         )

{vertracloud_api-0.2.0 → vertracloud_api-0.2.2}/src/vertracloud/types.py

@@ -249,7 +249,16 @@ class PutBillingDetailsBody(_PutBillingDetailsRequired, total=False):
 ApplicationLanguage = Literal[
     "javascript", "typescript", "bun", "python", "static", "php", "go", "ruby", "java", "rust"
 ]
-ApplicationStatus = Literal["up", "down"]
+ApplicationStatus = Literal["up", "down", "building"]
+ApplicationBuildError = Literal[
+    "BUILD_FAILED",
+    "BUILD_TIMEOUT",
+    "BUILD_INTERRUPTED",
+    "INSTALL_FAILED",
+    "INSTALL_OUT_OF_MEMORY",
+    "INSTALL_TIMEOUT",
+    "INSTALL_SHIELD_BLOCKED",
+]
 ApplicationFileType = Literal["file", "directory"]
 DatabaseStatus = Literal["up", "down"]
 ResourceType = Literal[1, 2]
@@ -298,6 +307,7 @@ class _APIApplicationRequired(TypedDict):
     offline_since: str | None
     shield_cooldown: APIApplicationShieldCooldown | None
     deploy: APIApplicationDeploySettings
+    last_build_error: ApplicationBuildError | None
 
 
 class APIApplication(_APIApplicationRequired, total=False):

{vertracloud_api-0.2.0 → vertracloud_api-0.2.2}/tests/test_blob.py

@@ -74,6 +74,16 @@ def test_put_small_is_multipart_on_objects() -> None:
     assert len(t.calls) == 1
 
 
+def test_put_and_copy_send_rename_on_conflict() -> None:
+    client, t = _setup()
+    t.queue_json({"response": OBJ})
+    t.queue_json({"response": OBJ})
+    client.blob.put("a/b.txt", b"hi", rename_on_conflict=True)
+    assert _q(t.calls[0])["rename_on_conflict"] == ["true"]
+    client.blob.copy("o1", "a/b.txt", rename_on_conflict=True)
+    assert json.loads(t.calls[1].body or b"{}") == {"source": "o1", "path": "a/b.txt", "rename_on_conflict": True}
+
+
 def test_put_from_path(tmp_path: Path) -> None:
     f = tmp_path / "x.txt"
     f.write_bytes(b"from-disk")

{vertracloud_api-0.2.0 → vertracloud_api-0.2.2}/tests/test_multipart_and_binary.py

@@ -118,3 +118,39 @@ def test_snapshot_download_returns_bytes() -> None:
     transport.queue_binary(b"zip-content")
     client = VertraClient(api_key="k", transport=transport)
     assert client.snapshots.download("user-1", "snap-1", "applications") == b"zip-content"
+
+
+def _app(status: str) -> dict:
+    return {"response": {"id": "app-1", "status": status}}
+
+
+def test_wait_until_ready_returns_app_when_up() -> None:
+    from vertracloud import VertraClient
+
+    transport = FakeTransport()
+    transport.queue_json(_app("building"))
+    transport.queue_json(_app("up"))
+    client = VertraClient(api_key="k", transport=transport)
+    assert client.apps.wait_until_ready("app-1", interval=0)["status"] == "up"
+    assert len(transport.calls) == 2
+
+
+def test_wait_until_ready_raises_on_down_and_timeout() -> None:
+    from vertracloud import AppBuildFailedError, VertraClient, WaitTimeoutError
+
+    transport = FakeTransport()
+    transport.queue_json(_app("down"))
+    client = VertraClient(api_key="k", transport=transport)
+    with pytest.raises(AppBuildFailedError) as down:
+        client.apps.wait_until_ready("app-1", interval=0)
+    assert down.value.code == "APP_DOWN"
+
+    transport.queue_json({"response": {"id": "app-1", "status": "down", "last_build_error": "INSTALL_OUT_OF_MEMORY"}})
+    with pytest.raises(AppBuildFailedError) as oom:
+        client.apps.wait_until_ready("app-1", interval=0)
+    assert oom.value.code == "INSTALL_OUT_OF_MEMORY"
+
+    transport.default_json = _app("building")
+    with pytest.raises(WaitTimeoutError) as slow:
+        client.apps.wait_until_ready("app-1", timeout=0, interval=0)
+    assert slow.value.code == "WAIT_TIMEOUT"

vertracloud_api-0.2.0/.release-please-manifest.json

@@ -1 +0,0 @@
-{".":"0.2.0"}