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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runcloud-sdk
-Version: 0.8.3
+Version: 0.9.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.9.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.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "runcloud-sdk"
-version = "0.8.3"
+version = "0.9.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.9.0}/runcloud/client.py

@@ -372,8 +372,17 @@ 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
+    ) -> list["Sandbox"]:
+        # Both filters are applied server-side, so finding a sandbox by the name
+        # you gave it does not mean paging the whole fleet and matching locally.
+        filters = [
+            (key, value)
+            for key, value in (("state", state), ("name", name))
+            if value
+        ]
+        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", [])]
 
@@ -548,6 +557,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.9.0/runcloud_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runcloud-sdk
-Version: 0.8.3
+Version: 0.9.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.9.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),