withruntime 0.3.0__tar.gz → 0.4.0__tar.gz

{withruntime-0.3.0 → withruntime-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: withruntime
-Version: 0.3.0
+Version: 0.4.0
 Summary: Runtime Cloud: one client (sync and async) for every Runtime product. Sandboxes first.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -50,10 +50,45 @@ A sandbox has `exec`, `exec_stream`, `spawn`, `terminal`, `files` (read, write,
 list, glob, stat, move, remove, upload and download directories), `pause`,
 `wake`, `extend`, `fork` and `snapshot`, and the `interpreter`, `network`,
 `previews` and `desktop` products. The client has `sandboxes`, `images`,
-`volumes`, `snapshots`, `feedback` and `support`. Every write carries an
+`volumes`, `snapshots`, `limits`, `feedback` and `support`;
+`runtime.limits.get()` (0.3.1 and later) says whether the key is read-only and
+what its agent may still spend today. Every write carries an
 idempotency key, so retries never do anything twice; errors are typed and carry
 `code`, `hint` and `request_id`.
 
+## Behind a proxy
+
+The client reads `HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY` (upper or lower
+case; lower wins when both are set), sync and async. Calls to the API and
+terminal WebSockets go through `HTTPS_PROXY` as a CONNECT tunnel, with any
+`user:password@` in its address sent to the proxy. `HTTP_PROXY` is used only
+for `http://` addresses, never for the HTTPS API. `NO_PROXY` lists hosts to
+reach directly, split by commas or spaces: a name covers its subdomains, a
+leading dot is allowed, `host:port` limits it to one port, and `*` means every
+host. A proxy address without a scheme is `http://`; only `http://` proxies are
+supported, and anything else fails at once with `invalid_proxy`. When a call
+cannot get through, the error names the proxy it tried (without the password),
+for example `No answer from Runtime at https://api.withruntime.com through the
+proxy http://proxy.internal:3128 (HTTPS_PROXY).`
+
+## Code written for E2B
+
+`withruntime.e2b` runs code written for E2B's Python SDK on Runtime. Change
+the import and set `RUNTIME_API_KEY`:
+
+```python no-run
+from withruntime.e2b import Sandbox, AsyncSandbox  # was: from e2b import ...
+from withruntime.e2b.code_interpreter import Sandbox  # was: from e2b_code_interpreter import Sandbox
+```
+
+Sandboxes get E2B's defaults: 2 vCPU, 512 MiB and a 300-second timeout.
+Timeouts are in seconds, as in E2B's Python SDK. `runtime_create={...}` passes
+Runtime's own create fields, for example `{"funding": "trial"}`. What Runtime
+does not do the way E2B does raises `NotSupportedException` before anything
+happens, naming what to use instead. Importing `withruntime` alone does not
+load it. The sync `Sandbox` is generated from the async one by
+`scripts/generate_e2b_sync.py`.
+
 Docs: https://withruntime.com/docs/python.
 
 The package was called `withruntime-cloud`, imported as `runtime_cloud`, until

withruntime-0.4.0/README.md

@@ -0,0 +1,89 @@
+# Runtime Cloud Python SDK
+
+One client for every Runtime Cloud product, sync and async. Python 3.10 or
+later, standard library only.
+
+```bash no-run
+pip install withruntime
+```
+
+The client uses `RUNTIME_API_KEY` when it is set, and otherwise the connection
+this machine saved when `npx withruntime login` connected it (one browser
+approval, no key to copy). On a server, set `RUNTIME_API_KEY` from your secret
+manager (create a key at https://withruntime.com/account/keys). Never put a key
+in source code, a URL or a command-line argument.
+
+```python
+from withruntime import Sandbox
+
+with Sandbox.create() as sbx:
+    result = sbx.exec("python3 -c 'print(6 * 7)'")
+    print(result.exit_code, result.stdout)
+```
+
+`Sandbox.create()` needs no arguments and returns once the sandbox is running;
+leaving the `with` block stops it. `AsyncRuntime` is the same client for
+asyncio, method for method:
+
+```python
+import asyncio
+from withruntime import AsyncRuntime
+
+
+async def main():
+    async with AsyncRuntime() as runtime:
+        async with await runtime.sandboxes.create() as sbx:
+            print((await sbx.exec("uname -a")).stdout)
+
+
+asyncio.run(main())
+```
+
+A sandbox has `exec`, `exec_stream`, `spawn`, `terminal`, `files` (read, write,
+list, glob, stat, move, remove, upload and download directories), `pause`,
+`wake`, `extend`, `fork` and `snapshot`, and the `interpreter`, `network`,
+`previews` and `desktop` products. The client has `sandboxes`, `images`,
+`volumes`, `snapshots`, `limits`, `feedback` and `support`;
+`runtime.limits.get()` (0.3.1 and later) says whether the key is read-only and
+what its agent may still spend today. Every write carries an
+idempotency key, so retries never do anything twice; errors are typed and carry
+`code`, `hint` and `request_id`.
+
+## Behind a proxy
+
+The client reads `HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY` (upper or lower
+case; lower wins when both are set), sync and async. Calls to the API and
+terminal WebSockets go through `HTTPS_PROXY` as a CONNECT tunnel, with any
+`user:password@` in its address sent to the proxy. `HTTP_PROXY` is used only
+for `http://` addresses, never for the HTTPS API. `NO_PROXY` lists hosts to
+reach directly, split by commas or spaces: a name covers its subdomains, a
+leading dot is allowed, `host:port` limits it to one port, and `*` means every
+host. A proxy address without a scheme is `http://`; only `http://` proxies are
+supported, and anything else fails at once with `invalid_proxy`. When a call
+cannot get through, the error names the proxy it tried (without the password),
+for example `No answer from Runtime at https://api.withruntime.com through the
+proxy http://proxy.internal:3128 (HTTPS_PROXY).`
+
+## Code written for E2B
+
+`withruntime.e2b` runs code written for E2B's Python SDK on Runtime. Change
+the import and set `RUNTIME_API_KEY`:
+
+```python no-run
+from withruntime.e2b import Sandbox, AsyncSandbox  # was: from e2b import ...
+from withruntime.e2b.code_interpreter import Sandbox  # was: from e2b_code_interpreter import Sandbox
+```
+
+Sandboxes get E2B's defaults: 2 vCPU, 512 MiB and a 300-second timeout.
+Timeouts are in seconds, as in E2B's Python SDK. `runtime_create={...}` passes
+Runtime's own create fields, for example `{"funding": "trial"}`. What Runtime
+does not do the way E2B does raises `NotSupportedException` before anything
+happens, naming what to use instead. Importing `withruntime` alone does not
+load it. The sync `Sandbox` is generated from the async one by
+`scripts/generate_e2b_sync.py`.
+
+Docs: https://withruntime.com/docs/python.
+
+The package was called `withruntime-cloud`, imported as `runtime_cloud`, until
+0.3.0. Both names still work: `withruntime-cloud` installs this package and
+`import runtime_cloud` gives you the same classes.

{withruntime-0.3.0 → withruntime-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "withruntime"
-version = "0.3.0"
+version = "0.4.0"
 description = "Runtime Cloud: one client (sync and async) for every Runtime product. Sandboxes first."
 readme = "README.md"
 requires-python = ">=3.10"

{withruntime-0.3.0 → withruntime-0.4.0}/tests/test_client.py

@@ -40,6 +40,15 @@ class Sync(unittest.TestCase):
                 piped = sbx.exec(["cat"], stdin="in", env={"TOKEN": "secret"})
                 self.assertIn("<in>", piped.stdout)
 
+    def test_fork_takes_funding_as_create_does(self):
+        # 23 September 2026: fork(funding="trial") was refused as "body.funding is
+        # not a known field". Forks are switched off on the fixture, so the real
+        # router's answer is the deliberate fork_unavailable, not a 400.
+        sbx = client().sandboxes.get(ID)
+        with self.assertRaises(ServiceUnavailableError) as caught:
+            sbx.fork(funding="trial")
+        self.assertEqual(caught.exception.code, "fork_unavailable")
+
     def test_check_raises_with_the_output(self):
         sbx = client().sandboxes.get(ID)
         with self.assertRaises(CommandError) as caught:

withruntime-0.4.0/tests/test_e2b_code_interpreter.py

@@ -0,0 +1,130 @@
+"""The code interpreter adapter against the fake withruntime SDK."""
+import asyncio
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from e2b_fake import World  # noqa: E402
+
+from withruntime.e2b.code_interpreter import (AsyncSandbox, CommandExitException, Context, Execution,  # noqa: E402
+                                              NotSupportedException, OutputMessage, Result, Sandbox,
+                                              TimeoutException)
+
+
+class RunCode(unittest.TestCase):
+    def setUp(self) -> None:
+        self.world = World()
+
+    def create(self, **kwargs):
+        return Sandbox.create(client=self.world.client(), **kwargs)
+
+    def test_python_by_default(self):
+        sbx = self.create()
+        execution = sbx.run_code("1 + 1")
+        self.assertIsInstance(execution, Execution)
+        self.assertEqual(execution.text, "2")
+        self.assertIsInstance(execution.results[0], Result)
+        self.assertEqual(execution.results[0].formats(), ["text"])
+        self.assertEqual((execution.logs.stdout, execution.logs.stderr), (["out 1 + 1\n"], []))
+        self.assertEqual(execution.execution_count, 1)
+        self.assertIsNone(execution.error)
+        self.assertEqual(self.world.called("interpreter.run")[0],
+                         ("1 + 1", {"language": "python", "timeout_ms": 60_000}))
+
+    def test_base_commands_still_work(self):
+        from e2b_fake import Result as Run
+        self.world.exec = lambda *_: Run(1, "", "no\n")
+        with self.assertRaises(CommandExitException):
+            self.create().commands.run("false")
+
+    def test_rich_results(self):
+        self.world.interpreter = lambda *_: {
+            "status": "ok", "stdout": "a\nb\npartial", "stderr": "warn\n", "executionCount": 4, "error": None,
+            "results": [
+                {"main": False, "data": {"image/png": "iVBOR", "text/plain": "<Figure>"}, "refs": {}},
+                {"main": True, "data": {"application/vnd.runtime.table+json": {"columns": ["a"]}},
+                 "refs": {"text/html": {"path": "/workspace/.runtime/interpreter/python/out/1.html"}}}]}
+        execution = self.create().run_code("df")
+        self.assertEqual(execution.logs.stdout, ["a\n", "b\n", "partial"])
+        figure, table = execution.results
+        self.assertEqual((figure.png, figure.text, figure.is_main_result), ("iVBOR", "<Figure>", False))
+        self.assertEqual(table.html, "bytes of /workspace/.runtime/interpreter/python/out/1.html")
+        self.assertEqual(table.extra, {"application/vnd.runtime.table+json": {"columns": ["a"]}})
+        self.assertIsNone(table.data)
+        self.assertIsNone(table.chart)
+
+    def test_errors_timeouts_and_refusals(self):
+        self.world.interpreter = lambda *_: {"status": "error", "stdout": "", "stderr": "", "results": [],
+                                             "error": {"name": "ZeroDivisionError", "value": "division by zero",
+                                                       "traceback": "..."}}
+        sbx = self.create()
+        self.assertEqual(sbx.run_code("1/0").error.name, "ZeroDivisionError")
+        self.world.interpreter = lambda *_: {"status": "timeout", "stdout": "", "stderr": "", "results": []}
+        with self.assertRaises(TimeoutException):
+            sbx.run_code("while True: pass", timeout=1)
+        for language in ("bash", "r", "typescript", "java"):
+            with self.assertRaises(NotSupportedException):
+                sbx.run_code("1", language=language)
+        with self.assertRaises(NotSupportedException):
+            sbx.run_code("1", envs={"A": "1"})
+
+    def test_streams(self):
+        sbx = self.create()
+        out, results = [], []
+        sbx.run_code("print(1)", on_stdout=out.append, on_result=results.append)
+        self.assertIsInstance(out[0], OutputMessage)
+        self.assertEqual((out[0].line, out[0].error), ("out print(1)\n", False))
+        self.assertEqual([one.text for one in results], ["2"])
+
+    def test_sandbox_envs_reach_code_through_one_context(self):
+        sbx = self.create(envs={"TOKEN": "t"})
+        sbx.run_code("import os")
+        sbx.run_code("os.environ['TOKEN']")
+        self.assertEqual(self.world.called("contexts.create"),
+                         [({"id": "e2b-python", "language": "python", "env": {"TOKEN": "t"}},)])
+        self.assertEqual([call[1] for call in self.world.called("interpreter.run")],
+                         [{"context": "e2b-python", "timeout_ms": 60_000}] * 2)
+        other = Sandbox.create(client=self.world.client(), envs={"TOKEN": "t"})
+        other.runtime.contexts["e2b-python"] = {"id": "e2b-python", "language": "python", "cwd": "/workspace"}
+        other.run_code("1")
+        self.assertEqual(self.world.called("interpreter.run")[-1][1]["context"], "e2b-python")
+
+    def test_contexts(self):
+        sbx = self.create()
+        context = sbx.create_code_context(cwd="/tmp", language="javascript")
+        self.assertEqual(context, Context("ctx-1", "javascript", "/tmp"))
+        self.assertEqual(sbx.list_code_contexts(), [context])
+        sbx.run_code("x", context=context)
+        self.assertEqual(self.world.called("interpreter.run")[0][1], {"context": "ctx-1", "timeout_ms": 60_000})
+        sbx.restart_code_context(context)
+        sbx.remove_code_context("ctx-1")
+        self.assertEqual(self.world.called("contexts.remove"), [("ctx-1",)])
+        with self.assertRaises(NotSupportedException):
+            sbx.create_code_context(language="r")
+
+
+class AsyncRunCode(unittest.TestCase):
+    def test_async(self):
+        world = World()
+
+        async def scenario():
+            seen = []
+
+            async def on_stdout(message):
+                seen.append(message.line)
+
+            sbx = await AsyncSandbox.create(client=world.async_client())
+            execution = await sbx.run_code("1 + 1", on_stdout=on_stdout)
+            await asyncio.sleep(0)
+            self.assertEqual(execution.text, "2")
+            self.assertEqual(seen, ["out 1 + 1\n"])
+            context = await sbx.create_code_context(language="python")
+            self.assertEqual((await sbx.list_code_contexts())[0].id, context.id)
+
+        asyncio.run(scenario())
+
+
+if __name__ == "__main__":
+    unittest.main()