runcloud-sdk 0.8.3__tar.gz → 0.10.0__tar.gz

{runcloud_sdk-0.8.3/runcloud_sdk.egg-info → runcloud_sdk-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runcloud-sdk
-Version: 0.8.3
+Version: 0.10.0
 Summary: Python SDK for run.cloud, including sandbox-provider compatibility adapters
 Author: Newly
 License-Expression: Apache-2.0
@@ -62,6 +62,21 @@ finally:
 automation, set `RUN_CLOUD_API_KEY` and optionally `RUN_CLOUD_API_URL`, or pass
 `api_key` and `api_url` directly.
 
+A sandbox's name is a label you own: set it at create, change it later, and
+filter on it. Naming plus `resume` is how the same sandbox goes back to the same
+piece of work instead of booting a new one:
+
+```python
+matches = cloud.list(name=f"project-{project_id}")
+box = matches[0].resume() if matches else cloud.create(name=f"project-{project_id}")
+
+box.rename(f"project-{project_id}-v2")
+box.rename("")  # clears the label
+```
+
+Names are not unique and mean nothing to the platform, so check `state` on a
+match before using it. Renaming works in any state but `destroyed`.
+
 ## Compatibility adapters
 
 The same distribution includes migration adapters:

{runcloud_sdk-0.8.3 → runcloud_sdk-0.10.0}/README.md

@@ -44,6 +44,21 @@ finally:
 automation, set `RUN_CLOUD_API_KEY` and optionally `RUN_CLOUD_API_URL`, or pass
 `api_key` and `api_url` directly.
 
+A sandbox's name is a label you own: set it at create, change it later, and
+filter on it. Naming plus `resume` is how the same sandbox goes back to the same
+piece of work instead of booting a new one:
+
+```python
+matches = cloud.list(name=f"project-{project_id}")
+box = matches[0].resume() if matches else cloud.create(name=f"project-{project_id}")
+
+box.rename(f"project-{project_id}-v2")
+box.rename("")  # clears the label
+```
+
+Names are not unique and mean nothing to the platform, so check `state` on a
+match before using it. Renaming works in any state but `destroyed`.
+
 ## Compatibility adapters
 
 The same distribution includes migration adapters:

{runcloud_sdk-0.8.3 → runcloud_sdk-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "runcloud-sdk"
-version = "0.8.3"
+version = "0.10.0"
 description = "Python SDK for run.cloud, including sandbox-provider compatibility adapters"
 readme = "README.md"
 requires-python = ">=3.9"

{runcloud_sdk-0.8.3 → runcloud_sdk-0.10.0}/runcloud/client.py

@@ -354,6 +354,7 @@ class Client:
         timeout_seconds: Optional[int] = None,
         region: Optional[str] = None,
         name: Optional[str] = None,
+        tags: Optional[dict[str, str]] = None,
     ) -> "Sandbox":
         values = {
             "image": image,
@@ -364,6 +365,7 @@ class Client:
             "timeoutSeconds": timeout_seconds,
             "region": region,
             "name": name,
+            "tags": tags,
         }
         body = {key: value for key, value in values.items() if value is not None}
         return Sandbox(self, self.request("POST", "/run-cloud/sandboxes", body))
@@ -372,8 +374,22 @@ class Client:
         sid = urllib.parse.quote(sandbox_id, safe="")
         return Sandbox(self, self.request("GET", f"/run-cloud/sandboxes/{sid}"))
 
-    def list(self, state: Optional[str] = None) -> list["Sandbox"]:
-        query = f"?state={urllib.parse.quote(state, safe='')}" if state else ""
+    def list(
+        self,
+        state: Optional[str] = None,
+        name: Optional[str] = None,
+        tags: Optional[dict[str, str]] = None,
+    ) -> list["Sandbox"]:
+        # Every filter is applied server-side, so finding a sandbox by the name
+        # you gave it does not mean paging the whole fleet and matching locally.
+        # Repeated `tag` params are ANDed together.
+        filters = [
+            (key, value)
+            for key, value in (("state", state), ("name", name))
+            if value
+        ]
+        filters.extend(("tag", f"{key}:{value}") for key, value in (tags or {}).items())
+        query = "?" + urllib.parse.urlencode(filters) if filters else ""
         payload = self.request("GET", "/run-cloud/sandboxes" + query) or {}
         return [Sandbox(self, item) for item in payload.get("items", [])]
 
@@ -392,6 +408,25 @@ class Sandbox:
     def name(self) -> str:
         return str(self._data.get("name") or "")
 
+    @property
+    def tags(self) -> dict[str, str]:
+        value = self._data.get("tags")
+        return dict(value) if isinstance(value, dict) else {}
+
+    def set_tags(self, tags: dict[str, Optional[str]]) -> "Sandbox":
+        """Merge tags into this sandbox. A None value deletes that key.
+
+        Tags survive the sandbox's destruction, so they stay usable for
+        attribution and support long after the sandbox is gone.
+        """
+        sid = urllib.parse.quote(self.id, safe="")
+        updated = self._client.request(
+            "PATCH", f"/run-cloud/sandboxes/{sid}/tags", {"tags": tags}
+        )
+        if isinstance(updated, dict) and isinstance(updated.get("tags"), dict):
+            self._data["tags"] = updated["tags"]
+        return self
+
     def refresh(self) -> "Sandbox":
         self._data = self._client.request(
             "GET", f"/run-cloud/sandboxes/{urllib.parse.quote(self.id, safe='')}"
@@ -548,6 +583,21 @@ class Sandbox:
         )
         return self
 
+    def rename(self, name: str) -> "Sandbox":
+        """Relabel the sandbox.
+
+        The name is a label you own and the filter ``list(name=...)`` matches on,
+        so this is how a sandbox gets re-tagged without destroying it. Works in
+        any state but destroyed; an empty name clears the label. Names are not
+        unique and are capped at 128 characters.
+        """
+        self._data = self._client.request(
+            "POST",
+            f"/run-cloud/sandboxes/{urllib.parse.quote(self.id, safe='')}/name",
+            {"name": name},
+        )
+        return self
+
     def set_timeout(self, seconds: int) -> "Sandbox":
         self._data = self._client.request(
             "POST",

{runcloud_sdk-0.8.3 → runcloud_sdk-0.10.0/runcloud_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runcloud-sdk
-Version: 0.8.3
+Version: 0.10.0
 Summary: Python SDK for run.cloud, including sandbox-provider compatibility adapters
 Author: Newly
 License-Expression: Apache-2.0
@@ -62,6 +62,21 @@ finally:
 automation, set `RUN_CLOUD_API_KEY` and optionally `RUN_CLOUD_API_URL`, or pass
 `api_key` and `api_url` directly.
 
+A sandbox's name is a label you own: set it at create, change it later, and
+filter on it. Naming plus `resume` is how the same sandbox goes back to the same
+piece of work instead of booting a new one:
+
+```python
+matches = cloud.list(name=f"project-{project_id}")
+box = matches[0].resume() if matches else cloud.create(name=f"project-{project_id}")
+
+box.rename(f"project-{project_id}-v2")
+box.rename("")  # clears the label
+```
+
+Names are not unique and mean nothing to the platform, so check `state` on a
+match before using it. Renaming works in any state but `destroyed`.
+
 ## Compatibility adapters
 
 The same distribution includes migration adapters:

{runcloud_sdk-0.8.3 → runcloud_sdk-0.10.0}/tests/test_sdk.py

@@ -114,6 +114,35 @@ class SDKTests(unittest.TestCase):
             self.recorder.calls,
         )
 
+    def test_rename_posts_the_label_and_list_filters_on_it(self):
+        box = self.client.create()
+        box.rename("proj_42")
+        self.assertIn(
+            ("POST", "/run-cloud/sandboxes/sb_python/name", {"name": "proj_42"}),
+            self.recorder.calls,
+        )
+        # The response replaces the cached record, so the new name is readable
+        # without a second get().
+        self.assertEqual(box.name, "compat")
+
+        # An empty name clears the label rather than being rejected client-side.
+        box.rename("")
+        self.assertIn(
+            ("POST", "/run-cloud/sandboxes/sb_python/name", {"name": ""}),
+            self.recorder.calls,
+        )
+
+        self.client.list(name="proj_42")
+        self.assertIn(
+            ("GET", "/run-cloud/sandboxes?name=proj_42", None),
+            self.recorder.calls,
+        )
+        self.client.list(state="running", name="proj 42")
+        self.assertIn(
+            ("GET", "/run-cloud/sandboxes?state=running&name=proj+42", None),
+            self.recorder.calls,
+        )
+
     def test_exec_contract_defaults_legacy_true_and_preserves_false(self):
         for frame, expected in [
             ({"stream": "exit"}, 0),
@@ -387,6 +416,35 @@ class SDKTests(unittest.TestCase):
         self.assertIsNone(delete_request.get_header("Content-type"))
         self.assertEqual(post_request.get_header("Content-type"), "application/json")
 
+    def test_tags_are_sent_on_create_and_exposed_on_the_record(self):
+        box = self.client.create(tags={"newly.session": "sess-1"})
+        method, path, body = self.recorder.calls[0]
+        self.assertEqual((method, path), ("POST", "/run-cloud/sandboxes"))
+        self.assertEqual(body["tags"], {"newly.session": "sess-1"})
+        # The fixture carries no tags, so an untagged payload must read as {}.
+        self.assertEqual(box.tags, {})
+
+    def test_create_omits_tags_when_none_are_given(self):
+        self.client.create()
+        _, _, body = self.recorder.calls[0]
+        self.assertNotIn("tags", body)
+
+    def test_list_ands_repeated_tag_filters(self):
+        self.client.list(state="running", tags={"newly.role": "agent", "env": "dev"})
+        _, path, _ = self.recorder.calls[0]
+        self.assertEqual(
+            path,
+            "/run-cloud/sandboxes?state=running&tag=newly.role%3Aagent&tag=env%3Adev",
+        )
+
+    def test_set_tags_patches_and_keeps_null_delete_markers(self):
+        box = self.client.create()
+        box.set_tags({"newly.role": "agent", "gone": None})
+        method, path, body = self.recorder.calls[-1]
+        self.assertEqual(method, "PATCH")
+        self.assertEqual(path, "/run-cloud/sandboxes/sb_python/tags")
+        self.assertEqual(body, {"tags": {"newly.role": "agent", "gone": None}})
+
 
 class CredentialTests(unittest.TestCase):
     def setUp(self):