impello 0.2.0__tar.gz

impello-0.2.0/.gitignore

@@ -0,0 +1,5 @@
+.venv
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

impello-0.2.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: impello
+Version: 0.2.0
+Summary: Python SDK for Impello sandboxes.
+Project-URL: Homepage, https://impello.ai
+Project-URL: Repository, https://github.com/21-Dreams/impello
+License-Expression: MIT
+Keywords: agents,code-interpreter,impello,microvm,sandbox
+Requires-Python: >=3.9
+Requires-Dist: e2b<3,>=2.46.0
+Description-Content-Type: text/markdown
+
+# `impello`
+
+The Python SDK for Impello sandboxes.
+
+## Install
+
+```bash
+pip install impello
+```
+
+## Use
+
+```python
+from impello import Sandbox
+
+sandbox = Sandbox.create()
+result = sandbox.commands.run("echo hello")
+
+print(result.stdout)
+
+sandbox.pause()
+```
+
+Set your key in the environment, or pass it to each call:
+
+```bash
+export IMPELLO_API_KEY=imp_...
+```
+
+```python
+Sandbox.list(api_key="imp_...")
+```
+
+For a process that talks to more than one account or more than one fleet, bind
+the settings to a client instead:
+
+```python
+from impello import Impello
+
+client = Impello(api_key="imp_...")
+sandbox = client.Sandbox.create()
+```
+
+## Settings
+
+Every setting reads an `IMPELLO_` name first, then the matching `E2B_` name.
+
+| Variable | Default | What it does |
+|---|---|---|
+| `IMPELLO_API_KEY` | none | The key. Starts with `imp_` |
+| `IMPELLO_DOMAIN` | `sandbox.impello.ai` | The domain the API and the sandboxes sit on |
+| `IMPELLO_API_URL` | `https://api.<domain>` | The API address. Set this to reach a self-hosted API |
+| `IMPELLO_SANDBOX_URL` | derived from the domain | The address a sandbox is reached at |
+| `IMPELLO_DEBUG` | `false` | Talk to `http://localhost:3000` |
+
+The `E2B_` fallback is the migration, not politeness. Callers already export
+`E2B_API_KEY`, `E2B_API_URL` and `E2B_DOMAIN`. Rename when it suits you.
+Nothing breaks if you never do.
+
+Only the domain has a default. Without one the SDK falls back to E2B's own
+`e2b.app`, and the failure is a connection to somebody else's fleet.
+
+Params passed to a single call beat a client's params, which beat the
+environment. That is E2B's own rule and this package keeps it.
+
+## Why this one is a wrapper, when the TypeScript one is a copy
+
+The TypeScript client cannot talk to Impello at all. Its `validateApiKey` runs
+inside the `ApiClient` constructor, is not exported, has no off switch, and
+accepts only `e2b_`. So `@impello/sdk` had to be a copy.
+
+Python has no `e2b_` pattern anywhere. It takes an `imp_` key today. So the
+only thing missing is where to send the request, and that is all this package
+supplies.
+
+It supplies it through `ClientFactory._resolve_api_params`, which is E2B's own
+seam for binding defaults. That means one method is overridden rather than the
+twelve descriptors on `Sandbox`, and **`e2b` itself is untouched**: importing
+`impello` does not retarget a plain `e2b` call in the same process, and it
+never writes to `os.environ`. A test holds that.
+
+## This package will be replaced
+
+A permanent wrapper is the worst outcome. `pip show impello` prints `e2b`, and
+the client sends a `publisher: e2b` header to our own servers. So the wrapper
+ships now and the full clone lands before we take payments, with
+`e2b/api/client/` regenerated from our own spec.
+
+See `docs/decisions/sdk-self-contained.md`.
+
+## Develop
+
+```bash
+python -m venv .venv
+./.venv/bin/pip install -e . pytest
+./.venv/bin/python -m pytest
+```

impello-0.2.0/README.md

@@ -0,0 +1,97 @@
+# `impello`
+
+The Python SDK for Impello sandboxes.
+
+## Install
+
+```bash
+pip install impello
+```
+
+## Use
+
+```python
+from impello import Sandbox
+
+sandbox = Sandbox.create()
+result = sandbox.commands.run("echo hello")
+
+print(result.stdout)
+
+sandbox.pause()
+```
+
+Set your key in the environment, or pass it to each call:
+
+```bash
+export IMPELLO_API_KEY=imp_...
+```
+
+```python
+Sandbox.list(api_key="imp_...")
+```
+
+For a process that talks to more than one account or more than one fleet, bind
+the settings to a client instead:
+
+```python
+from impello import Impello
+
+client = Impello(api_key="imp_...")
+sandbox = client.Sandbox.create()
+```
+
+## Settings
+
+Every setting reads an `IMPELLO_` name first, then the matching `E2B_` name.
+
+| Variable | Default | What it does |
+|---|---|---|
+| `IMPELLO_API_KEY` | none | The key. Starts with `imp_` |
+| `IMPELLO_DOMAIN` | `sandbox.impello.ai` | The domain the API and the sandboxes sit on |
+| `IMPELLO_API_URL` | `https://api.<domain>` | The API address. Set this to reach a self-hosted API |
+| `IMPELLO_SANDBOX_URL` | derived from the domain | The address a sandbox is reached at |
+| `IMPELLO_DEBUG` | `false` | Talk to `http://localhost:3000` |
+
+The `E2B_` fallback is the migration, not politeness. Callers already export
+`E2B_API_KEY`, `E2B_API_URL` and `E2B_DOMAIN`. Rename when it suits you.
+Nothing breaks if you never do.
+
+Only the domain has a default. Without one the SDK falls back to E2B's own
+`e2b.app`, and the failure is a connection to somebody else's fleet.
+
+Params passed to a single call beat a client's params, which beat the
+environment. That is E2B's own rule and this package keeps it.
+
+## Why this one is a wrapper, when the TypeScript one is a copy
+
+The TypeScript client cannot talk to Impello at all. Its `validateApiKey` runs
+inside the `ApiClient` constructor, is not exported, has no off switch, and
+accepts only `e2b_`. So `@impello/sdk` had to be a copy.
+
+Python has no `e2b_` pattern anywhere. It takes an `imp_` key today. So the
+only thing missing is where to send the request, and that is all this package
+supplies.
+
+It supplies it through `ClientFactory._resolve_api_params`, which is E2B's own
+seam for binding defaults. That means one method is overridden rather than the
+twelve descriptors on `Sandbox`, and **`e2b` itself is untouched**: importing
+`impello` does not retarget a plain `e2b` call in the same process, and it
+never writes to `os.environ`. A test holds that.
+
+## This package will be replaced
+
+A permanent wrapper is the worst outcome. `pip show impello` prints `e2b`, and
+the client sends a `publisher: e2b` header to our own servers. So the wrapper
+ships now and the full clone lands before we take payments, with
+`e2b/api/client/` regenerated from our own spec.
+
+See `docs/decisions/sdk-self-contained.md`.
+
+## Develop
+
+```bash
+python -m venv .venv
+./.venv/bin/pip install -e . pytest
+./.venv/bin/python -m pytest
+```

impello-0.2.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "impello"
+version = "0.2.0"
+description = "Python SDK for Impello sandboxes."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+keywords = ["impello", "sandbox", "microvm", "agents", "code-interpreter"]
+dependencies = [
+  # Pinned to a major. The next major may move `_resolve_api_params`, which is
+  # the one seam this package is built on. See src/impello/_defaults.py.
+  "e2b>=2.46.0,<3",
+]
+
+[project.urls]
+Homepage = "https://impello.ai"
+Repository = "https://github.com/21-Dreams/impello"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/impello"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

impello-0.2.0/src/impello/__init__.py

@@ -0,0 +1,84 @@
+"""The Python SDK for Impello sandboxes.
+
+Impello runs its own build of E2B's open-source ``infra``, so the sandbox API
+is the same API. Unlike the TypeScript client, the Python one needs no changes
+to work against it: there is no ``e2b_`` key pattern anywhere in ``e2b``, so it
+takes an ``imp_`` key today. All this package has to supply is where to send
+the request.
+
+So this is a wrapper, and it is deliberately thin. It will be replaced by a
+full clone before we take payments, for the same reason the TypeScript client
+is one: ``pip show impello`` printing ``e2b`` is a poor thing for a paid
+product to say about itself, and the client sends a ``publisher: e2b`` header
+to our own servers. See ``docs/decisions/sdk-self-contained.md``.
+
+Usage is E2B's, unchanged::
+
+    from impello import Sandbox
+
+    sandbox = Sandbox.create()
+    result = sandbox.commands.run("echo hello")
+    sandbox.pause()
+"""
+
+import e2b as _e2b
+from e2b import *  # noqa: F401,F403
+from e2b.connection_config import ApiParams, merge_api_params
+
+from ._defaults import DEFAULT_DOMAIN, defaults
+
+__version__ = "0.2.0"
+
+
+class _ImpelloDefaults:
+    """Bind Impello's settings underneath every call.
+
+    ``ClientFactory._resolve_api_params`` is E2B's own seam for this: every
+    class method funnels through it, and ``merge_api_params`` already gives
+    per-call params precedence over bound ones. So this overrides one method
+    instead of mirroring the twelve descriptors on ``Sandbox``, and it changes
+    nothing about ``e2b`` itself. Importing this package does not retarget a
+    plain ``e2b`` call in the same process, and it does not touch ``os.environ``.
+    """
+
+    @classmethod
+    def _resolve_api_params(cls, **opts: "ApiParams") -> "ApiParams":
+        return merge_api_params(defaults(), super()._resolve_api_params(**opts))
+
+
+class Sandbox(_ImpelloDefaults, _e2b.Sandbox):
+    """An Impello sandbox."""
+
+
+class AsyncSandbox(_ImpelloDefaults, _e2b.AsyncSandbox):
+    """An Impello sandbox, async."""
+
+
+class Impello(_e2b.E2B):
+    """A client with its connection settings bound explicitly.
+
+    Use this instead of the module-level ``Sandbox`` when one process talks to
+    more than one account or more than one fleet. Clients are isolated from
+    each other. Params passed here beat the environment; params passed to a
+    single call beat both.
+
+    Example::
+
+        from impello import Impello
+
+        client = Impello(api_key="imp_...")
+        sandbox = client.Sandbox.create()
+    """
+
+    def __init__(self, **opts: "ApiParams"):
+        super().__init__(**merge_api_params(defaults(), opts))
+
+
+__all__ = [
+    *[name for name in dir(_e2b) if not name.startswith("_")],
+    "Sandbox",
+    "AsyncSandbox",
+    "Impello",
+    "DEFAULT_DOMAIN",
+    "__version__",
+]

impello-0.2.0/src/impello/_defaults.py

@@ -0,0 +1,57 @@
+"""Where an Impello setting comes from, and in what order.
+
+Every setting reads an ``IMPELLO_`` name first, then the matching ``E2B_``
+name. The fallback is the migration, not politeness: callers already export
+``E2B_API_KEY``, ``E2B_API_URL`` and ``E2B_DOMAIN``, and the flag day that
+changes the key prefix is hard enough without renaming every environment on the
+same afternoon. Rename when convenient. Nothing breaks if you never do.
+"""
+
+import os
+from typing import Optional
+
+from e2b.connection_config import ApiParams
+
+DEFAULT_DOMAIN = "sandbox.impello.ai"
+
+# Each entry is one setting and the ``ApiParams`` key it fills.
+_SETTINGS = (
+    ("API_KEY", "api_key"),
+    ("API_URL", "api_url"),
+    ("DOMAIN", "domain"),
+    ("SANDBOX_URL", "sandbox_url"),
+)
+
+
+def _read(name: str) -> Optional[str]:
+    """Read one setting, Impello's name first."""
+    return os.getenv(f"IMPELLO_{name}") or os.getenv(f"E2B_{name}")
+
+
+def defaults() -> ApiParams:
+    """The params bound to every Impello call, resolved fresh each time.
+
+    Read at call time rather than at import, so a test or a caller that sets an
+    environment variable after importing this package still gets it.
+
+    A setting that is absent is left out of the result. It must not appear as
+    ``None``, because ``merge_api_params`` drops a ``None`` from the per-call
+    params but keeps one in the bound params, where it would clear the value
+    the SDK would otherwise resolve for itself.
+    """
+    params = {}
+
+    for name, key in _SETTINGS:
+        value = _read(name)
+        if value:
+            params[key] = value
+
+    debug = _read("DEBUG")
+    if debug:
+        params["debug"] = debug.lower() == "true"
+
+    # Only the domain has a default. Without one the SDK falls back to E2B's
+    # own `e2b.app`, and the failure is a connection to somebody else's fleet.
+    params.setdefault("domain", DEFAULT_DOMAIN)
+
+    return params

impello-0.2.0/tests/test_binding.py

@@ -0,0 +1,81 @@
+"""How the settings reach a call, and what must still beat them."""
+
+import e2b
+import pytest
+
+import impello
+from impello._defaults import DEFAULT_DOMAIN
+
+API_KEY = "imp_" + "0" * 40
+
+
+@pytest.fixture(autouse=True)
+def clean_env(monkeypatch):
+    for name in ("API_KEY", "API_URL", "DOMAIN", "SANDBOX_URL", "DEBUG"):
+        monkeypatch.delenv(f"IMPELLO_{name}", raising=False)
+        monkeypatch.delenv(f"E2B_{name}", raising=False)
+
+
+def test_a_call_is_pointed_at_impello():
+    assert impello.Sandbox._resolve_api_params()["domain"] == DEFAULT_DOMAIN
+
+
+def test_the_async_sandbox_is_pointed_there_too():
+    assert impello.AsyncSandbox._resolve_api_params()["domain"] == DEFAULT_DOMAIN
+
+
+def test_a_per_call_param_still_wins():
+    """E2B's own precedence rule. Breaking it would make a self-hosted or
+    second-account call unreachable."""
+    resolved = impello.Sandbox._resolve_api_params(domain="elsewhere.test")
+    assert resolved["domain"] == "elsewhere.test"
+
+
+def test_a_per_call_none_does_not_clear_the_default():
+    resolved = impello.Sandbox._resolve_api_params(domain=None)
+    assert resolved["domain"] == DEFAULT_DOMAIN
+
+
+def test_the_environment_reaches_the_call(monkeypatch):
+    monkeypatch.setenv("IMPELLO_API_KEY", API_KEY)
+    assert impello.Sandbox._resolve_api_params()["api_key"] == API_KEY
+
+
+def test_plain_e2b_is_left_alone():
+    """Importing this package must not retarget somebody else's e2b call in
+    the same process. That is why this binds a subclass instead of patching
+    ConnectionConfig or writing to os.environ."""
+    assert e2b.Sandbox._resolve_api_params() == {}
+    assert e2b.connection_config.ConnectionConfig().domain == "e2b.app"
+
+
+def test_an_impello_client_binds_the_defaults():
+    client = impello.Impello(api_key=API_KEY)
+    assert client.Sandbox._resolve_api_params()["domain"] == DEFAULT_DOMAIN
+    assert client.Sandbox._resolve_api_params()["api_key"] == API_KEY
+
+
+def test_an_impello_client_can_be_pointed_elsewhere():
+    client = impello.Impello(api_key=API_KEY, domain="elsewhere.test")
+    assert client.Sandbox._resolve_api_params()["domain"] == "elsewhere.test"
+
+
+def test_the_sandbox_is_still_an_e2b_sandbox():
+    """The wrapper adds settings. It must not fork behaviour."""
+    assert issubclass(impello.Sandbox, e2b.Sandbox)
+    assert issubclass(impello.AsyncSandbox, e2b.AsyncSandbox)
+
+
+def test_the_surface_is_re_exported():
+    for name in ("SandboxException", "SandboxNotFoundException", "SandboxQuery"):
+        assert getattr(impello, name) is getattr(e2b, name)
+
+
+def test_the_resolved_params_build_the_impello_address():
+    """The end of the chain. Everything above is plumbing; this is the value
+    that decides which fleet the request reaches."""
+    from e2b.connection_config import ConnectionConfig
+
+    config = ConnectionConfig(**impello.Sandbox._resolve_api_params())
+
+    assert config.api_url == "https://api.sandbox.impello.ai"

impello-0.2.0/tests/test_defaults.py

@@ -0,0 +1,78 @@
+"""What a setting resolves to, and what it must never resolve to."""
+
+import pytest
+
+from impello._defaults import DEFAULT_DOMAIN, defaults
+
+SETTINGS = [
+    ("API_KEY", "api_key"),
+    ("API_URL", "api_url"),
+    ("DOMAIN", "domain"),
+    ("SANDBOX_URL", "sandbox_url"),
+]
+
+
+@pytest.fixture(autouse=True)
+def clean_env(monkeypatch):
+    """Neither prefix is set unless a test sets it."""
+    for name, _ in SETTINGS + [("DEBUG", "debug")]:
+        monkeypatch.delenv(f"IMPELLO_{name}", raising=False)
+        monkeypatch.delenv(f"E2B_{name}", raising=False)
+
+
+def test_the_domain_defaults_to_impello():
+    """Without this the SDK falls back to E2B's own `e2b.app`, and the failure
+    is a connection to somebody else's fleet."""
+    assert defaults()["domain"] == DEFAULT_DOMAIN
+
+
+def test_nothing_else_is_invented():
+    """Only the domain has a default. Every other key must be absent, not
+    None: merge_api_params keeps a None in the bound params, where it would
+    clear a value the SDK would otherwise resolve for itself."""
+    assert set(defaults()) == {"domain"}
+
+
+@pytest.mark.parametrize("name,key", SETTINGS)
+def test_impello_name_is_read(monkeypatch, name, key):
+    monkeypatch.setenv(f"IMPELLO_{name}", "from-impello")
+    assert defaults()[key] == "from-impello"
+
+
+@pytest.mark.parametrize("name,key", SETTINGS)
+def test_e2b_name_is_the_fallback(monkeypatch, name, key):
+    """Callers already export the E2B names. Renaming every environment on
+    flag day is not a thing this package asks for."""
+    monkeypatch.setenv(f"E2B_{name}", "from-e2b")
+    assert defaults()[key] == "from-e2b"
+
+
+@pytest.mark.parametrize("name,key", SETTINGS)
+def test_impello_name_wins_when_both_are_set(monkeypatch, name, key):
+    monkeypatch.setenv(f"IMPELLO_{name}", "from-impello")
+    monkeypatch.setenv(f"E2B_{name}", "from-e2b")
+    assert defaults()[key] == "from-impello"
+
+
+@pytest.mark.parametrize("name,key", SETTINGS)
+def test_an_empty_value_is_not_a_value(monkeypatch, name, key):
+    monkeypatch.setenv(f"IMPELLO_{name}", "")
+    monkeypatch.setenv(f"E2B_{name}", "from-e2b")
+    assert defaults()[key] == "from-e2b"
+
+
+def test_debug_is_read_as_a_flag(monkeypatch):
+    monkeypatch.setenv("IMPELLO_DEBUG", "TRUE")
+    assert defaults()["debug"] is True
+
+
+def test_debug_is_false_when_it_says_anything_else(monkeypatch):
+    monkeypatch.setenv("IMPELLO_DEBUG", "yes")
+    assert defaults()["debug"] is False
+
+
+def test_settings_are_read_at_call_time_not_import_time(monkeypatch):
+    """A caller that configures itself after importing still gets it."""
+    assert "api_key" not in defaults()
+    monkeypatch.setenv("IMPELLO_API_KEY", "imp_" + "0" * 40)
+    assert defaults()["api_key"] == "imp_" + "0" * 40