solari-e2b-compat 0.1.0__py3-none-any.whl

solari_e2b/__init__.py

@@ -0,0 +1,39 @@
+# ruff: noqa: F401
+"""solari_e2b: an E2B-compatible Python API on Solari Sandbox. Not affiliated with E2B. See README.md, COMPAT.md, NOTICE.
+
+``from solari_e2b import Sandbox`` (blocking) or ``AsyncSandbox``; ``from solari_e2b.code_interpreter import Sandbox`` for
+``run_code``."""
+
+from __future__ import annotations
+
+from ._commands import AsyncCommandHandle, AsyncCommandInputHandle, AsyncCommands, AsyncPty
+from ._config import DEFAULT_BASE_URL, is_solari_base_url
+from ._filesystem import AsyncFileStreamReader, AsyncFilesystem, AsyncWatchHandle
+from ._sandbox import AsyncSandbox, AsyncSandboxPaginator, AsyncSnapshotPaginator
+from ._sync import Sandbox
+from ._template import (
+    AsyncTemplate,
+    BuildInfo,
+    LogEntry,
+    LogEntryEnd,
+    LogEntryStart,
+    ReadyCmd,
+    Template,
+    TemplateBase,
+    TemplateBuildStatusResponse,
+    default_build_logger,
+    wait_for_file,
+    wait_for_port,
+    wait_for_process,
+    wait_for_timeout,
+    wait_for_url,
+)
+from .exceptions import *  # noqa: F401,F403
+from .exceptions import _Unsupported
+from .models import *  # noqa: F401,F403
+
+#: E2B's Volume and Secret APIs have no Solari equivalent yet: every call raises SolariCompatUnsupported.
+Volume = _Unsupported("Volume")
+Secret = _Unsupported("Secret")
+
+__version__ = "0.1.0"

solari_e2b/_box.py

@@ -0,0 +1,155 @@
+"""Per-sandbox plumbing shared by Sandbox, Commands, Filesystem and Pty: the live control handle (reconnecting after a
+resume), the guest's $HOME, and the shell wrapper E2B-style ``commands.run`` needs."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from typing import Any, Awaitable, Callable, List, Optional, Tuple, TypeVar
+from urllib.parse import quote
+
+from solari_core.errors import ConnectionError as SolariConnection, GatewayError, SolariError
+
+from ._config import Conn
+from .exceptions import translate
+
+T = TypeVar("T")
+DEFAULT_HOME = "/home/user"
+
+#: Native image sandboxes: a bash when the image has one, else sh. The command is "$1", so it is never re-parsed.
+NATIVE_SHELL_SCRIPT = 'if [ -x /bin/bash ]; then exec /bin/bash -c "$1"; else exec /bin/sh -c "$1"; fi'
+
+
+def shell_args(native: bool, command: str) -> Tuple[str, List[str]]:
+    """``(program, args)`` for an E2B-style shell string: ``bash -lc`` normally, native-image safe otherwise."""
+    if native:
+        return "/bin/sh", ["-c", NATIVE_SHELL_SCRIPT, "sh", command]
+    return "/bin/bash", ["-lc", command]
+
+
+async def get_view(conn: Conn, sandbox_id: str) -> dict:
+    """Raw ``GET /sandboxes/:id`` (the Python SDK view drops ``fromImage`` and the creation time)."""
+    return await conn.http.request("GET", f"/sandboxes/{quote(sandbox_id, safe='')}")
+
+
+def fire(cb: Optional[Callable[..., Any]], *args: Any) -> None:
+    """Invoke a user callback now if it is sync, or schedule it if it is async; an exception in it never breaks the stream."""
+    if cb is None:
+        return
+    try:
+        r = cb(*args)
+        if inspect.isawaitable(r):
+            asyncio.ensure_future(r)
+    except Exception:  # noqa: BLE001
+        pass
+
+
+async def call_cb(cb: Optional[Callable[..., Any]], *args: Any) -> None:
+    """Invoke a user callback (sync or async); an exception in it never breaks the stream."""
+    if cb is None:
+        return
+    try:
+        r = cb(*args)
+        if inspect.isawaitable(r):
+            await r
+    except Exception:  # noqa: BLE001
+        pass
+
+
+class Box:
+    def __init__(self, conn: Conn, sandbox_id: str, initial: Any = None) -> None:
+        self.conn = conn
+        self.id = sandbox_id
+        self._h: Optional["asyncio.Future[Any]"] = None
+        self._initial = initial
+        self._native: Optional["asyncio.Future[bool]"] = None
+        self._home: Optional["asyncio.Future[str]"] = None
+
+    async def handle(self) -> Any:
+        """The connected control handle, cached."""
+        if self._h is None:
+            self._h = asyncio.ensure_future(self._attach())
+        try:
+            return await asyncio.shield(self._h)
+        except BaseException:
+            if self._h is not None and self._h.done():
+                self._h = None
+            raise
+
+    async def _attach(self) -> Any:
+        sb = self._initial if self._initial is not None else await self.conn.solari.connect(self.id)
+        self._initial = None
+        await sb.connect()
+        return sb
+
+    def drop(self) -> None:
+        self._h = None
+        self._initial = None
+
+    async def close(self) -> None:
+        """Close this process's control channel to the sandbox (if one is open) and forget it."""
+        h, self._h = self._h, None
+        initial, self._initial = self._initial, None
+        sb = initial
+        if h is not None and h.done() and not h.cancelled() and h.exception() is None:
+            sb = h.result()
+        if sb is not None:
+            try:
+                await sb.close()
+            except Exception:  # noqa: BLE001
+                pass
+
+    async def on(self, fn: Callable[[Any], Awaitable[T]], what: str = "other") -> T:
+        """Run ``fn`` on the live handle; if the channel was closed under us (first call after a resume), reconnect and retry."""
+        attempt = 0
+        while True:
+            try:
+                return await fn(await self.handle())
+            except Exception as e:  # noqa: BLE001
+                closed = isinstance(e, SolariError) and not isinstance(e, GatewayError) and (
+                    isinstance(e, SolariConnection) or any(w in str(e).lower() for w in ("closed", "not connected", "disconnect", "websocket"))
+                )
+                if not closed or attempt >= 2:
+                    raise translate(e, what) from (e if translate(e, what) is not e else None)
+                self.drop()
+                attempt += 1
+                await asyncio.sleep(0.5 * attempt)
+
+    async def is_native(self) -> bool:
+        if self._native is None:
+            self._native = asyncio.ensure_future(self._fetch_native())
+        try:
+            return await asyncio.shield(self._native)
+        except BaseException:
+            self._native = None
+            raise
+
+    async def _fetch_native(self) -> bool:
+        return bool((await get_view(self.conn, self.id)).get("fromImage"))
+
+    async def home(self) -> str:
+        """The guest's $HOME (E2B's default cwd and relative-path base), created if missing."""
+        if self._home is None:
+            self._home = asyncio.ensure_future(self._fetch_home())
+        try:
+            return await asyncio.shield(self._home)
+        except BaseException:
+            self._home = None
+            raise
+
+    async def _fetch_home(self) -> str:
+        prog, args = shell_args(await self.is_native(), 'printf %s "$HOME"')
+        r = await self.on(lambda sb: sb.commands.run(prog, args=args))
+        home = r.stdout.strip() or DEFAULT_HOME
+        await self.on(lambda sb: sb.commands.run("/bin/mkdir", args=["-p", home]))
+        return home
+
+    async def abs(self, path: str) -> str:
+        if path.startswith("/"):
+            return path
+        home = await self.home()
+        if path == "~":
+            return home
+        if path.startswith("~/"):
+            return f"{home}/{path[2:]}"
+        return f"{home}/{path}"

solari_e2b/_commands.py

@@ -0,0 +1,307 @@
+"""E2B ``sandbox.commands`` and ``sandbox.pty``. Solari identifies a running command by a string id that lives on the
+creating control channel, so E2B's numeric ``pid`` values are process-local handles: list/connect/kill/send_stdin work for
+commands started by this process (see COMPAT.md)."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Union
+
+from ._box import Box, fire, shell_args
+from .exceptions import CommandExitException, CommandResult, NotFoundException, SandboxException, SolariCompatUnsupported, TimeoutException, translate
+from .models import ProcessInfo, PtySize
+
+DEFAULT_COMMAND_TIMEOUT = 60.0
+_next_pid = 1000
+_procs: Dict[str, Dict[int, "_Rec"]] = {}
+
+
+class _Rec:
+    def __init__(self, pid: int, info: ProcessInfo, handle: "AsyncCommandHandle", kind: str) -> None:
+        self.pid, self.info, self.handle, self.kind, self.exited = pid, info, handle, kind, False
+
+
+def _procs_of(sandbox_id: str) -> Dict[int, _Rec]:
+    return _procs.setdefault(sandbox_id, {})
+
+
+def _alloc_pid() -> int:
+    global _next_pid
+    _next_pid += 1
+    return _next_pid - 1
+
+
+class AsyncCommandHandle:
+    """What ``commands.run(..., background=True)`` and ``pty.create`` return."""
+
+    def __init__(
+        self,
+        pid: int,
+        kill: Callable[[], Awaitable[None]],
+        stdin: Callable[[Union[str, bytes]], Awaitable[None]],
+        pty: bool = False,
+    ) -> None:
+        self._pid = pid
+        self._kill, self._stdin, self._pty = kill, stdin, pty
+        self._stdout = ""
+        self._stderr = ""
+        self._exit: Optional[int] = None
+        self._error: Optional[str] = None
+        self._done: "asyncio.Future[None]" = asyncio.get_running_loop().create_future()
+        self._on_stdout: List[Callable[..., Any]] = []
+        self._on_stderr: List[Callable[..., Any]] = []
+        self._on_pty: List[Callable[..., Any]] = []
+
+    @property
+    def pid(self) -> int:
+        return self._pid
+
+    @property
+    def stdout(self) -> str:
+        return self._stdout
+
+    @property
+    def stderr(self) -> str:
+        return self._stderr
+
+    @property
+    def exit_code(self) -> Optional[int]:
+        return self._exit
+
+    @property
+    def error(self) -> Optional[str]:
+        return self._error
+
+    # --- fed by the transport ---
+    def _data(self, stream: str, data: str) -> None:
+        if stream == "stdout":
+            self._stdout += data
+            cbs = self._on_stdout
+        else:
+            self._stderr += data
+            cbs = self._on_stderr
+        for cb in list(cbs):
+            fire(cb, data)
+
+    def _pty_data(self, data: bytes) -> None:
+        for cb in list(self._on_pty):
+            fire(cb, data)
+
+    def _exited(self, code: int, error: Optional[str] = None) -> None:
+        if self._exit is not None:
+            return
+        self._exit, self._error = code, error
+        if not self._done.done():
+            self._done.set_result(None)
+
+    async def wait(self, on_pty=None, on_stdout=None, on_stderr=None) -> CommandResult:
+        """Wait for the command to end. Raises :class:`CommandExitException` on a non-zero exit, as E2B does."""
+        if on_stdout:
+            self._on_stdout.append(on_stdout)
+        if on_stderr:
+            self._on_stderr.append(on_stderr)
+        if on_pty:
+            self._on_pty.append(on_pty)
+        await asyncio.shield(self._done)
+        r = CommandResult(stderr=self._stderr, stdout=self._stdout, exit_code=self._exit or 0, error=self._error)
+        if r.exit_code != 0:
+            raise CommandExitException(r.stderr, r.stdout, r.exit_code, r.error)
+        return r
+
+    async def disconnect(self) -> None:
+        """Stop receiving output; the command keeps running."""
+        self._on_stdout.clear()
+        self._on_stderr.clear()
+        self._on_pty.clear()
+
+    async def kill(self) -> bool:
+        """SIGKILL. ``False`` when the command already ended."""
+        if self._exit is not None:
+            return False
+        try:
+            await self._kill()
+        except Exception as e:  # noqa: BLE001
+            raise translate(e) from e
+        if self._pty:
+            self._exited(137, "killed")
+        return True
+
+    async def send_stdin(self, data: Union[str, bytes], request_timeout: Optional[float] = None) -> None:
+        try:
+            await self._stdin(data)
+        except Exception as e:  # noqa: BLE001
+            raise translate(e) from e
+
+    async def close_stdin(self, request_timeout: Optional[float] = None) -> None:
+        raise SolariCompatUnsupported("close_stdin", "Solari cannot close a command's stdin; end the program another way (for example a sentinel line)")
+
+
+class AsyncCommandInputHandle:
+    """Ordered input stream, built over repeated writes (Solari writes are ordered per command)."""
+
+    def __init__(self, write: Callable[[Union[str, bytes]], Awaitable[None]]) -> None:
+        self._write = write
+        self._closed = False
+
+    async def send(self, data: Union[str, bytes]) -> None:
+        if self._closed:
+            raise SandboxException("The input stream is closed")
+        await self._write(data)
+
+    async def close(self) -> None:
+        self._closed = True
+
+
+class AsyncCommands:
+    def __init__(self, box: Box) -> None:
+        self._box = box
+
+    @property
+    def supports_stdin_close(self) -> bool:
+        return False
+
+    async def run(
+        self,
+        cmd: str,
+        background: Optional[bool] = None,
+        envs: Optional[Dict[str, str]] = None,
+        user: Optional[str] = None,
+        cwd: Optional[str] = None,
+        on_stdout: Optional[Callable[..., Any]] = None,
+        on_stderr: Optional[Callable[..., Any]] = None,
+        stdin: Optional[bool] = None,
+        timeout: Optional[float] = DEFAULT_COMMAND_TIMEOUT,
+        request_timeout: Optional[float] = None,
+    ) -> Union[CommandResult, AsyncCommandHandle]:
+        handle = await self._start(cmd, envs, user, cwd, on_stdout, on_stderr)
+        if background:
+            return handle
+        if timeout:
+            try:
+                return await asyncio.wait_for(handle.wait(), timeout)
+            except asyncio.TimeoutError:
+                try:
+                    await handle.kill()
+                except Exception:  # noqa: BLE001
+                    pass
+                raise TimeoutException(f"Command timed out after {timeout:g}s") from None
+        return await handle.wait()
+
+    async def _start(self, cmd, envs, user, cwd, on_stdout, on_stderr) -> AsyncCommandHandle:
+        native = await self._box.is_native()
+        program, args = shell_args(native, cmd)
+        # E2B runs commands from the user's home directory unless told otherwise.
+        wd = await self._box.abs(cwd) if cwd else await self._box.home()
+        core = await self._box.on(lambda sb: sb.commands.start(program, args=args, cwd=wd, env=envs, user=user))
+        pid = _alloc_pid()
+        handle = AsyncCommandHandle(pid, core.kill, core.stdin)
+        if on_stdout:
+            handle._on_stdout.append(on_stdout)
+        if on_stderr:
+            handle._on_stderr.append(on_stderr)
+        core.on_data(handle._data)
+        rec = _Rec(pid, ProcessInfo(pid=pid, cmd=program, args=args, envs=envs or {}, cwd=wd), handle, "cmd")
+        _procs_of(self._box.id)[pid] = rec
+
+        async def _watch() -> None:
+            try:
+                code = await core.wait()
+                rec.exited = True
+                handle._exited(code)
+            except Exception as e:  # noqa: BLE001
+                rec.exited = True
+                handle._exited(1, str(e))
+
+        asyncio.ensure_future(_watch())
+        return handle
+
+    async def list(self, request_timeout: Optional[float] = None) -> List[ProcessInfo]:
+        """Commands and PTYs this process started on the sandbox that have not ended."""
+        return [r.info for r in _procs_of(self._box.id).values() if not r.exited]
+
+    def _known(self, pid: int) -> _Rec:
+        rec = _procs_of(self._box.id).get(pid)
+        if rec is None:
+            raise NotFoundException(f"Process {pid} not found. Solari can only address commands started by this process (see COMPAT.md).")
+        return rec
+
+    async def kill(self, pid: int, request_timeout: Optional[float] = None) -> bool:
+        rec = _procs_of(self._box.id).get(pid)
+        if rec is None or rec.exited:
+            return False
+        return await rec.handle.kill()
+
+    async def send_stdin(self, pid: int, data: Union[str, bytes], request_timeout: Optional[float] = None) -> None:
+        await self._known(pid).handle.send_stdin(data)
+
+    def stream_input(self, pid: int, *, timeout: Optional[float] = None) -> AsyncCommandInputHandle:
+        return AsyncCommandInputHandle(self._known(pid).handle.send_stdin)
+
+    async def close_stdin(self, pid: int, request_timeout: Optional[float] = None) -> None:
+        await self._known(pid).handle.close_stdin()
+
+    async def connect(self, pid: int, timeout: Optional[float] = 60, request_timeout: Optional[float] = None, on_stdout=None, on_stderr=None) -> AsyncCommandHandle:
+        h = self._known(pid).handle
+        if on_stdout:
+            h._on_stdout.append(on_stdout)
+        if on_stderr:
+            h._on_stderr.append(on_stderr)
+        return h
+
+
+class AsyncPty:
+    def __init__(self, box: Box) -> None:
+        self._box = box
+
+    async def create(
+        self,
+        size: PtySize,
+        on_data: Callable[[bytes], Any],
+        user: Optional[str] = None,
+        cwd: Optional[str] = None,
+        envs: Optional[Dict[str, str]] = None,
+        timeout: Optional[float] = 60,
+        request_timeout: Optional[float] = None,
+    ) -> AsyncCommandHandle:
+        if user:
+            raise SolariCompatUnsupported("pty.create user")
+        env = {"TERM": "xterm-256color", **(envs or {})}
+        core = await self._box.on(lambda sb: sb.pty.create(cols=size.cols, rows=size.rows, cwd=cwd, env=env))
+        pid = _alloc_pid()
+        handle = AsyncCommandHandle(pid, core.kill, core.write, pty=True)
+        handle._on_pty.append(on_data)
+        core.on_data(handle._pty_data)
+        handle._pty_core = core  # type: ignore[attr-defined]
+        _procs_of(self._box.id)[pid] = _Rec(pid, ProcessInfo(pid=pid, cmd="pty", envs=envs or {}, cwd=cwd), handle, "pty")
+        return handle
+
+    def _pty(self, pid: int) -> _Rec:
+        rec = _procs_of(self._box.id).get(pid)
+        if rec is None or rec.kind != "pty":
+            raise NotFoundException(f"PTY {pid} not found. Solari can only address PTYs created by this process (see COMPAT.md).")
+        return rec
+
+    async def connect(self, pid: int, on_data: Callable[[bytes], Any], timeout: Optional[float] = 60, request_timeout: Optional[float] = None) -> AsyncCommandHandle:
+        rec = self._pty(pid)
+        rec.handle._on_pty.append(on_data)
+        return rec.handle
+
+    async def send_stdin(self, pid: int, data: bytes, request_timeout: Optional[float] = None) -> None:
+        await self._pty(pid).handle.send_stdin(data)
+
+    def stream_input(self, pid: int, *, timeout: Optional[float] = None) -> AsyncCommandInputHandle:
+        return AsyncCommandInputHandle(self._pty(pid).handle.send_stdin)
+
+    async def resize(self, pid: int, size: PtySize, request_timeout: Optional[float] = None) -> None:
+        core = self._pty(pid).handle._pty_core  # type: ignore[attr-defined]
+        try:
+            await core.resize(size.cols, size.rows)
+        except Exception as e:  # noqa: BLE001
+            raise translate(e) from e
+
+    async def kill(self, pid: int, request_timeout: Optional[float] = None) -> bool:
+        rec = _procs_of(self._box.id).get(pid)
+        if rec is None or rec.kind != "pty" or rec.exited:
+            return False
+        rec.exited = True
+        return await rec.handle.kill()

solari_e2b/_config.py

@@ -0,0 +1,128 @@
+"""Credential and base-URL resolution. Only a Solari key (``slr_…``) is ever used or sent; E2B's own environment variables
+(``E2B_API_KEY``, ``E2B_API_URL``, ``E2B_DOMAIN``) are honoured only when they are safe to send a Solari key to."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional, Tuple
+from urllib.parse import urlparse
+
+import httpx
+from solari_core import HttpTransport, TemplateClient
+from solari_sandbox import SandboxClient
+
+from .exceptions import SandboxException, SolariCompatUnsupported
+
+log = logging.getLogger("solari_e2b")
+
+DEFAULT_BASE_URL = "https://api.getsolari.com"
+KEY_PREFIX = "slr_"
+
+#: Per-call connection options the E2B SDK accepts (``**opts`` on most methods).
+API_OPTS = frozenset(
+    {"api_key", "domain", "api_url", "request_timeout", "debug", "headers", "api_headers", "proxy", "logger", "sandbox_url", "validate_api_key", "retries", "http_version"}
+)
+#: Accepted and ignored: they tune E2B's own transport.
+IGNORED_OPTS = frozenset({"request_timeout", "debug", "logger", "validate_api_key", "retries", "http_version", "sandbox_url"})
+
+#: Test hook: a callable returning the ``httpx.AsyncClient`` the clients should use (a MockTransport client in tests).
+_HTTP_FACTORY: Optional[Callable[[], httpx.AsyncClient]] = None
+
+
+def is_solari_base_url(raw: str) -> bool:
+    """https on getsolari.com or a subdomain, or loopback over http(s)."""
+    try:
+        u = urlparse(raw)
+        host = (u.hostname or "").lower().rstrip(".")
+    except ValueError:
+        return False
+    if u.scheme == "https" and (host == "getsolari.com" or host.endswith(".getsolari.com")):
+        return True
+    return u.scheme in ("http", "https") and (host in ("localhost", "::1") or host.replace(".", "").isdigit() and host.startswith("127."))
+
+
+def _describe(raw: str) -> str:
+    try:
+        return urlparse(raw).hostname or "unparsable URL"
+    except ValueError:
+        return "unparsable URL"
+
+
+@dataclass
+class Conn:
+    api_key: str
+    base_url: str
+    solari: SandboxClient
+    http: HttpTransport
+    templates: TemplateClient
+
+
+_cache: Dict[Tuple[str, str, int], Conn] = {}
+
+
+def _resolve(opts: Dict[str, Any]) -> Tuple[str, str]:
+    if opts.get("headers"):
+        raise SolariCompatUnsupported("headers")
+    if opts.get("api_headers"):
+        raise SolariCompatUnsupported("api_headers")
+    if opts.get("proxy"):
+        raise SolariCompatUnsupported("proxy")
+    key: Optional[str] = None
+    for source, value in (("the api_key option", opts.get("api_key")), ("SOLARI_API_KEY", os.environ.get("SOLARI_API_KEY")), ("E2B_API_KEY", os.environ.get("E2B_API_KEY"))):
+        if not value:
+            continue
+        if value.startswith(KEY_PREFIX):
+            key = value
+            break
+        log.warning("Ignoring %s: it is not a Solari API key (%s…). It is not sent anywhere.", source, KEY_PREFIX)
+    if not key:
+        raise SandboxException(
+            "No Solari API key. Set SOLARI_API_KEY, or pass api_key='slr_live_…'. An E2B key (E2B_API_KEY) is never sent to Solari and cannot be used here."
+        )
+    explicit = opts.get("api_url") or (f"https://api.{opts['domain']}" if opts.get("domain") else None)
+    base: Optional[str] = None
+    if explicit:
+        if not is_solari_base_url(explicit):
+            raise SandboxException(f"Refusing to send a Solari API key to {_describe(explicit)}: it does not point at Solari.")
+        base = explicit
+    inherited_raw = os.environ.get("E2B_API_URL") or (f"https://api.{os.environ['E2B_DOMAIN']}" if os.environ.get("E2B_DOMAIN") else None)
+    inherited: Optional[str] = None
+    if inherited_raw:
+        if is_solari_base_url(inherited_raw):
+            inherited = inherited_raw
+        elif not base and not os.environ.get("SOLARI_BASE_URL"):
+            log.warning(
+                "Ignoring E2B_API_URL/E2B_DOMAIN (%s): it does not point at Solari, and your Solari API key is never sent anywhere else. Using %s.",
+                _describe(inherited_raw),
+                DEFAULT_BASE_URL,
+            )
+    return key, (base or os.environ.get("SOLARI_BASE_URL") or inherited or DEFAULT_BASE_URL).rstrip("/")
+
+
+def resolve_conn(**opts: Any) -> Conn:
+    """Connection for one call, cached per key + URL + running event loop (httpx clients are loop-bound)."""
+    key, base = _resolve(opts)
+    loop_id = id(asyncio.get_running_loop())
+    ck = (key, base, loop_id)
+    c = _cache.get(ck)
+    if c is None:
+        http = _HTTP_FACTORY() if _HTTP_FACTORY else None
+        c = Conn(
+            api_key=key,
+            base_url=base,
+            solari=SandboxClient(api_key=key, base_url=base, http=http),
+            http=HttpTransport(api_key=key, base_url=base, http=http),
+            templates=TemplateClient(api_key=key, base_url=base, http=http),
+        )
+        _cache[ck] = c
+    return c
+
+
+def split_opts(kwargs: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    """Separate connection options from the rest of a call's keyword arguments."""
+    opts = {k: v for k, v in kwargs.items() if k in API_OPTS}
+    rest = {k: v for k, v in kwargs.items() if k not in API_OPTS}
+    return opts, rest