boxd 0.2.6.dev355__tar.gz → 0.2.6.dev398__tar.gz

{boxd-0.2.6.dev355/src/boxd.egg-info → boxd-0.2.6.dev398}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boxd
-Version: 0.2.6.dev355
+Version: 0.2.6.dev398
 Summary: Python SDK for the boxd cloud VM platform
 Author: Azin
 License-Expression: MIT

{boxd-0.2.6.dev355 → boxd-0.2.6.dev398}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "boxd"
-version = "0.2.6.dev355"
+version = "0.2.6.dev398"
 description = "Python SDK for the boxd cloud VM platform"
 readme = "README.md"
 license = "MIT"

{boxd-0.2.6.dev355 → boxd-0.2.6.dev398}/src/boxd/_mappers.py

@@ -80,6 +80,11 @@ def _epoch_ms_always(millis: int) -> datetime:
 # ── Machines ─────────────────────────────────────────────────────────
 
 
+def _desktop_url(name: str, console_origin: str) -> str:
+    """`<console>/desktop/<name>`, or "" when the console origin is unknown."""
+    return f"{console_origin}/desktop/{name}" if console_origin else ""
+
+
 def _machine_url(name: str, domain: str) -> str:
     """`https://<name>.<domain>`, or "" when the domain is not known yet."""
     return f"https://{name}.{domain}" if domain else ""
@@ -99,7 +104,7 @@ def machine_source(msg) -> MachineSource | None:
     )
 
 
-def machine(msg) -> Machine:
+def machine(msg, console_origin: str = "") -> Machine:
     # `billing_org`/`billing_org_id` name the machine's org whether or not it
     # is shared. `org`/`org_id` are the same org, blanked when it is private —
     # so they answer "is it shared", and nothing else.
@@ -131,6 +136,7 @@ def machine(msg) -> Machine:
             ssh_port=msg.ssh_port or None,
             domain=msg.access_domain,
             url=_machine_url(msg.name, msg.access_domain),
+            desktop_url=_desktop_url(msg.name, console_origin),
             custom_domains=[custom_domain(d) for d in msg.custom_domains],
         ),
         # 0 is MEANINGFUL here — disabled, not unset. Do not null it.
@@ -167,7 +173,9 @@ def machine_from_created(msg) -> Machine:
         # Not reported by these responses — `create`/`fork` re-read the
         # machine, so this fallback only shows when that read failed.
         networking=MachineNetworking(networks=[], isolated=False),
-        access=MachineAccess(ssh_port=None, domain="", url="", custom_domains=[]),
+        access=MachineAccess(
+            ssh_port=None, domain="", url="", desktop_url="", custom_domains=[]
+        ),
         idle=MachineIdle(suspend_after=0, hibernate_after=0, destroy_after=0),
         source=None,
         hibernated_at=None,

{boxd-0.2.6.dev355 → boxd-0.2.6.dev398}/src/boxd/_transport.py

@@ -17,7 +17,7 @@ import grpc.aio
 from . import _version_check
 from ._credentials import AsyncCredentials, SyncCredentials
 from ._generated import api_pb2_grpc
-from ._urls import DEFAULT_BASE_URL, resolve_endpoint
+from ._urls import DEFAULT_BASE_URL, console_base_url, resolve_endpoint
 from .errors import BoxdError, from_grpc_error, is_retryable
 
 # First backoff, doubled per attempt. Two retries by default ⇒ 0.5s then 1.0s.
@@ -49,6 +49,17 @@ class _TransportBase:
             or DEFAULT_BASE_URL
         )
 
+    @property
+    def console_origin(self) -> str:
+        """The web console's origin for whichever cluster this client talks to.
+
+        Derived from the same `base_url` the channel dials, so the two can
+        never disagree. Note it cannot come from a machine's own
+        `access.domain`: that may be the ORG's wildcard domain, and the
+        console is never under it.
+        """
+        return console_base_url(self.base_url)
+
     def _build_channel(self, factory_secure, factory_insecure):
         endpoint = resolve_endpoint(self.base_url)
         if endpoint.use_tls:

{boxd-0.2.6.dev355 → boxd-0.2.6.dev398}/src/boxd/_version_check.py

@@ -11,6 +11,7 @@ produced; the comparison and the nag are shared.
 
 from __future__ import annotations
 
+import os
 import re
 import sys
 from collections.abc import Iterable
@@ -18,6 +19,7 @@ from collections.abc import Iterable
 REQ_HEADER = "x-boxd-py-sdk-version"
 RESP_HEADER = "x-boxd-py-sdk-latest"
 UPGRADE_CMD = "pip install --upgrade boxd"
+PRERELEASE_UPGRADE_CMD = "pip install --upgrade --pre boxd"
 
 _notified = False
 
@@ -40,6 +42,15 @@ def note_metadata(md: Iterable[tuple[str, str]] | None) -> None:
     global _notified
     if _notified or md is None:
         return
+    # Only for a person at a terminal: in CI, or in an automation job whose
+    # stderr is its log file, this is noise on every run and nothing acts on
+    # it.
+    # An explicit opt-out beats every heuristic: set BOXD_NO_UPDATE_NOTICE to
+    # any non-empty value and this is never printed.
+    if os.environ.get("BOXD_NO_UPDATE_NOTICE"):
+        return
+    if not _stderr_is_tty():
+        return
     latest = None
     for key, value in md:
         if key.lower() == RESP_HEADER:
@@ -50,13 +61,38 @@ def note_metadata(md: Iterable[tuple[str, str]] | None) -> None:
     current = _current_version()
     if _compare_semver(latest, current) <= 0:
         return
+    # A pre-release is opt-in (`pip install --pre`), so someone on a release
+    # build is not behind on anything they asked for — and the command below
+    # would not install it anyway, leaving the nag to repeat forever. Staging
+    # advertises its own pre-releases, so this is the normal case there.
+    if _is_prerelease(latest) and not _is_prerelease(current):
+        return
     _notified = True
     print(file=sys.stderr)
     print(
         f"  A new version of boxd is available (v{latest}, you have v{current}). Update with:",
         file=sys.stderr,
     )
-    print(f"    {UPGRADE_CMD}", file=sys.stderr)
+    cmd = PRERELEASE_UPGRADE_CMD if _is_prerelease(latest) else UPGRADE_CMD
+    print(f"    {cmd}", file=sys.stderr)
+
+
+def _stderr_is_tty() -> bool:
+    """Is stderr a terminal? Indirected through a function so tests can say.
+
+    (A capture fixture replaces ``sys.stderr`` wholesale, so patching the
+    stream's ``isatty`` is not something a test can rely on.)
+    """
+    try:
+        return bool(sys.stderr.isatty())
+    except Exception:  # closed or exotic stream: not a terminal
+        return False
+
+
+def _is_prerelease(v: str) -> bool:
+    """Does this version carry a pre-release suffix ("0.2.6.dev356")?"""
+    m = _SEMVER_RE.match(v.strip())
+    return bool(m and m.group(4))
 
 
 _SEMVER_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)(.*)$")

{boxd-0.2.6.dev355 → boxd-0.2.6.dev398}/src/boxd/models.py

@@ -68,6 +68,11 @@ class MachineAccess(BaseModel):
     """The domain the machine is addressed under."""
     url: str
     """`https://<name>.<domain>` — built for you, not sent by the server."""
+    desktop_url: str = ""
+    """The machine's live Desktop view in the console —
+    `https://app.<zone>/desktop/<name>`. Built for you, like `url`. Empty when
+    the client has no endpoint to derive the console origin from. Opening it
+    needs a signed-in browser; the machine is woken if it is asleep."""
     custom_domains: list[CustomDomain]
     """Per-VM custom domains bound to this machine (BOX-30), e.g.
     `app.example.com`. Distinct from `domain` above, which is the org's

{boxd-0.2.6.dev355 → boxd-0.2.6.dev398}/src/boxd/resources/machines.py

@@ -259,7 +259,8 @@ class Machines(Namespace):
     def get(self, machine_id: str) -> Machine:
         """Fetch one machine by id or name."""
         return m.machine(
-            self._transport.call("GetVm", api_pb2.GetVmRequest(vm_id=machine_id))
+            self._transport.call("GetVm", api_pb2.GetVmRequest(vm_id=machine_id)),
+            self._transport.console_origin,
         )
 
     def list(self, *, org: str | None = None, all_contexts: bool = False) -> list[Machine]:
@@ -271,7 +272,8 @@ class Machines(Namespace):
         resp = self._transport.call(
             "ListVms", req.list_vms(org=org, all_contexts=all_contexts)
         )
-        return [m.machine(v) for v in resp.vms]
+        console_origin = self._transport.console_origin
+        return [m.machine(v, console_origin) for v in resp.vms]
 
     def delete(self, machine_id: str) -> None:
         """Destroy a machine. Terminal."""
@@ -828,7 +830,8 @@ class AsyncMachines(Namespace):
     async def get(self, machine_id: str) -> Machine:
         """Fetch one machine by id or name."""
         return m.machine(
-            await self._transport.call("GetVm", api_pb2.GetVmRequest(vm_id=machine_id))
+            await self._transport.call("GetVm", api_pb2.GetVmRequest(vm_id=machine_id)),
+            self._transport.console_origin,
         )
 
     async def list(
@@ -838,7 +841,8 @@ class AsyncMachines(Namespace):
         resp = await self._transport.call(
             "ListVms", req.list_vms(org=org, all_contexts=all_contexts)
         )
-        return [m.machine(v) for v in resp.vms]
+        console_origin = self._transport.console_origin
+        return [m.machine(v, console_origin) for v in resp.vms]
 
     async def delete(self, machine_id: str) -> None:
         """Destroy a machine. Terminal."""

{boxd-0.2.6.dev355 → boxd-0.2.6.dev398/src/boxd.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boxd
-Version: 0.2.6.dev355
+Version: 0.2.6.dev398
 Summary: Python SDK for the boxd cloud VM platform
 Author: Azin
 License-Expression: MIT

{boxd-0.2.6.dev355 → boxd-0.2.6.dev398}/tests/test_mappers.py

@@ -518,3 +518,15 @@ def test_backup_dedup_pointer_and_checksum_are_absent_on_a_dedup_row():
     assert backup.status == "dedup"
     assert backup.checksum is None
     assert backup.points_to_backup_id == "bkp-1"
+
+
+def test_desktop_url_is_the_console_origin_plus_the_name():
+    """Built client-side like `url`, and empty rather than half-built when the
+    client has no endpoint to derive a console origin from."""
+    from boxd import _mappers as m
+
+    vm = a_vm(name="box")
+    assert m.machine(vm, "https://app.boxd.sh").access.desktop_url == (
+        "https://app.boxd.sh/desktop/box"
+    )
+    assert m.machine(vm).access.desktop_url == ""

{boxd-0.2.6.dev355 → boxd-0.2.6.dev398}/tests/test_namespaces.py

@@ -767,6 +767,7 @@ def test_machines_list_returns_a_plain_list():
     machines = Machines(transport).list()
     assert isinstance(machines, list)
     assert [x.name for x in machines] == ["alpha", "beta"]
+    assert machines[0].access.desktop_url == "https://app.boxd.sh/desktop/alpha"
 
 
 def test_machines_list_is_empty_when_the_account_has_none():

{boxd-0.2.6.dev355 → boxd-0.2.6.dev398}/tests/test_version_check.py

@@ -13,6 +13,16 @@ from boxd._version_check import (
     request_metadata,
 )
 
+
+@pytest.fixture(autouse=True)
+def _stderr_is_a_terminal(monkeypatch):
+    """The nag is for a person at a terminal, and pytest is not one.
+
+    Every test here assumes a TTY unless it says otherwise; the one that
+    checks the non-terminal case overrides this.
+    """
+    monkeypatch.setattr(_version_check, "_stderr_is_tty", lambda: True)
+
 # Picked to be unambiguously newer/older than any real shipped SDK so tests
 # don't silently flip meaning when the package version bumps.
 NEWER = "99.0.0"
@@ -119,3 +129,40 @@ def test_header_lookup_is_case_insensitive(stub_current, capsys):
 def test_header_value_is_stripped(stub_current, capsys):
     note_metadata([(RESP_HEADER, f"  {NEWER}  ")])
     assert NEWER in capsys.readouterr().err
+
+
+def test_silent_when_stderr_is_not_a_terminal(monkeypatch, capsys):
+    """CI, or an automation job whose stderr IS its log file: noise on every run."""
+    monkeypatch.setattr(_version_check, "_notified", False)
+    monkeypatch.setattr(_version_check, "_stderr_is_tty", lambda: False)
+    _version_check.note_metadata([(_version_check.RESP_HEADER, "99.0.0")])
+    assert capsys.readouterr().err == ""
+
+
+def test_silent_when_latest_is_a_prerelease_and_we_are_on_a_release(monkeypatch, capsys):
+    """A pre-release is opt-in (`pip install --pre`), and `--upgrade` alone
+    cannot install it — so the nag would repeat forever."""
+    monkeypatch.setattr(_version_check, "_notified", False)
+    monkeypatch.setattr(_version_check, "_current_version", lambda: "0.2.4")
+    _version_check.note_metadata([(_version_check.RESP_HEADER, "0.2.6.dev356")])
+    assert capsys.readouterr().err == ""
+
+
+def test_prerelease_user_is_told_the_prerelease_command(monkeypatch, capsys):
+    monkeypatch.setattr(_version_check, "_notified", False)
+    monkeypatch.setattr(_version_check, "_current_version", lambda: "0.2.6.dev1")
+    _version_check.note_metadata([(_version_check.RESP_HEADER, "0.2.6.dev356")])
+    assert "--pre" in capsys.readouterr().err
+
+
+def test_is_prerelease():
+    assert _version_check._is_prerelease("0.2.6.dev356")
+    assert _version_check._is_prerelease("0.2.6-dev.356")
+    assert not _version_check._is_prerelease("0.2.6")
+
+
+def test_silent_when_the_opt_out_env_var_is_set(monkeypatch, capsys):
+    monkeypatch.setattr(_version_check, "_notified", False)
+    monkeypatch.setenv("BOXD_NO_UPDATE_NOTICE", "1")
+    _version_check.note_metadata([(_version_check.RESP_HEADER, "99.0.0")])
+    assert capsys.readouterr().err == ""