levers9 0.2.0__tar.gz → 0.2.2__tar.gz

{levers9-0.2.0 → levers9-0.2.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: levers9
-Version: 0.2.0
-Summary: levers9 SDK and CLI: run functions, endpoints, task queues, schedules, pods and GPU jobs on a levers9 cluster
+Version: 0.2.2
+Summary: levers9 SDK and CLI: run jobs, endpoints, queues, crons, boxes and GPU work on a levers9 cluster
 Author-email: Levers AI Lab <hello@uselevers.com>
 Requires-Python: <4.0,>=3.8
 Requires-Dist: typeguard<3.0.0,>=2.13.3; python_version < "3.9"

{levers9-0.2.0 → levers9-0.2.2}/pyproject.toml

@@ -27,8 +27,8 @@ dependencies = [
     "pyyaml<7.0.0,>=6.0.0",
 ]
 name = "levers9"
-version = "0.2.0"
-description = "levers9 SDK and CLI: run functions, endpoints, task queues, schedules, pods and GPU jobs on a levers9 cluster"
+version = "0.2.2"
+description = "levers9 SDK and CLI: run jobs, endpoints, queues, crons, boxes and GPU work on a levers9 cluster"
 
 [project.scripts]
 levers9 = "levers9.cli.main:start"

{levers9-0.2.0 → levers9-0.2.2}/src/levers9/cli/main.py

@@ -143,6 +143,15 @@ def start():
     """Used as entrypoint in Poetry"""
     cli = load_cli()
 
+    # atexit, rather than wrapping the call: click owns its exit codes, --help handling and error
+    # rendering, and taking that over with standalone_mode=False silently breaks subcommand help.
+    # This runs after the command, however it ended, and cannot change its result.
+    import atexit
+
+    from .update_check import print_notice
+
+    atexit.register(print_notice)
+
     try:
         cli()
     except grpc.RpcError as error:

levers9-0.2.2/src/levers9/cli/update_check.py

@@ -0,0 +1,198 @@
+"""Tell someone when a newer levers9 is out, without ever making them wait for it.
+
+The check never happens on the path the user is waiting on. A command reads a small cache file and, if it
+already knows about a newer release, prints one line. Refreshing that cache is left to a daemon thread whose
+result lands in time for the *next* command, so a cold or slow network costs nothing now. Everything here is
+best-effort: a failure to reach PyPI, a corrupt cache or a read-only home directory all end in silence,
+because an update notice is never worth failing a command over.
+
+Off with LEVERS9_NO_UPDATE_CHECK=1, and off in CI by default.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Optional, Tuple
+
+PACKAGE = "levers9"
+PYPI_URL = f"https://pypi.org/pypi/{PACKAGE}/json"
+CHECK_INTERVAL_S = 24 * 60 * 60
+NOTIFY_INTERVAL_S = 24 * 60 * 60
+NETWORK_TIMEOUT_S = 2.0
+
+
+def _cache_path() -> Path:
+    return Path("~/.levers9").expanduser() / "update-check.json"
+
+
+def _read_cache() -> dict:
+    try:
+        return json.loads(_cache_path().read_text())
+    except (OSError, ValueError):
+        return {}
+
+
+def _write_cache(latest: str, **extra) -> None:
+    try:
+        p = _cache_path()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        data = {**_read_cache(), "latest": latest, "checked_at": time.time(), **extra}
+        p.write_text(json.dumps(data))
+    except OSError:
+        pass  # read-only home, no disk: not worth a word
+
+
+def _mark_notified() -> None:
+    try:
+        p = _cache_path()
+        data = {**_read_cache(), "notified_at": time.time()}
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(json.dumps(data))
+    except OSError:
+        pass
+
+
+def _installed_version() -> Optional[str]:
+    try:
+        from importlib.metadata import version
+
+        return version(PACKAGE)
+    except Exception:
+        return None
+
+
+def _parse(v: str) -> Tuple:
+    """Compare releases numerically, and sort any pre-release below its own final version."""
+    core = v.split("+", 1)[0]
+    for sep in ("a", "b", "rc", ".dev"):
+        if sep in core:
+            core = core.split(sep, 1)[0]
+            pre = True
+            break
+    else:
+        pre = False
+    parts = []
+    for piece in core.split("."):
+        try:
+            parts.append(int(piece))
+        except ValueError:
+            parts.append(0)
+    while len(parts) < 3:
+        parts.append(0)
+    return (*parts[:3], 0 if pre else 1)
+
+
+def is_newer(latest: str, installed: str) -> bool:
+    try:
+        return _parse(latest) > _parse(installed)
+    except Exception:
+        return False
+
+
+def _fetch_latest() -> Optional[str]:
+    try:
+        import urllib.request
+
+        req = urllib.request.Request(PYPI_URL, headers={"Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=NETWORK_TIMEOUT_S) as r:
+            return json.load(r)["info"]["version"]
+    except Exception:
+        return None
+
+
+# Run in a process of its own, detached, rather than a thread: most commands finish in well under the
+# time a request to PyPI takes, and a daemon thread dies with the interpreter, so the cache would never
+# actually be written and the notice would never appear. This is why update-notifier and friends reach
+# for a child process too.
+_REFRESH_SCRIPT = """
+import json, os, time, urllib.request
+try:
+    req = urllib.request.Request(%(url)r, headers={"Accept": "application/json"})
+    with urllib.request.urlopen(req, timeout=%(timeout)r) as r:
+        latest = json.load(r)["info"]["version"]
+    p = %(cache)r
+    os.makedirs(os.path.dirname(p), exist_ok=True)
+    tmp = p + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump({"latest": latest, "checked_at": time.time()}, f)
+    os.replace(tmp, p)
+except Exception:
+    pass
+"""
+
+
+def _refresh_in_background() -> None:
+    """Best effort, and deliberately fire-and-forget: nothing waits for this, including the caller."""
+    try:
+        # Touch the cache first so a burst of commands does not each spawn a refresher.
+        _write_cache(_read_cache().get("latest") or "")
+
+        code = _REFRESH_SCRIPT % {
+            "url": PYPI_URL,
+            "timeout": NETWORK_TIMEOUT_S,
+            "cache": str(_cache_path()),
+        }
+        devnull = subprocess.DEVNULL
+        subprocess.Popen(
+            [sys.executable, "-c", code],
+            stdin=devnull,
+            stdout=devnull,
+            stderr=devnull,
+            start_new_session=True,   # survives the CLI exiting
+        )
+    except Exception:
+        pass
+
+
+def disabled() -> bool:
+    if os.getenv("LEVERS9_NO_UPDATE_CHECK") or os.getenv("CI"):
+        return True
+    # Nothing is read by a person when output is being captured, and a notice written into a pipe is
+    # corruption rather than help: `levers9 ls > out.json` must produce only the json.
+    try:
+        return not sys.stderr.isatty()
+    except Exception:
+        return True
+
+
+def notice() -> Optional[str]:
+    """The line to show, or None. Reads the cache only; never touches the network on this path."""
+    if disabled():
+        return None
+
+    installed = _installed_version()
+    if not installed:
+        return None
+
+    cache = _read_cache()
+    if time.time() - float(cache.get("checked_at") or 0) > CHECK_INTERVAL_S:
+        _refresh_in_background()  # for next time; this run uses whatever is already cached
+
+    latest = cache.get("latest")
+    if not latest or not is_newer(latest, installed):
+        return None
+
+    # Say it once a day, not once a command. Someone running twenty commands does not need telling twenty
+    # times, and a notice that repeats is one people learn to read past.
+    if time.time() - float(cache.get("notified_at") or 0) < NOTIFY_INTERVAL_S:
+        return None
+
+    return f"levers9 {latest} is available (you have {installed}) · uv tool upgrade levers9"
+
+
+def print_notice() -> None:
+    """Best-effort, and silent about its own failures."""
+    try:
+        line = notice()
+        if not line:
+            return
+        # stderr, so it never lands in output a caller is parsing
+        print(f"\n\033[2m{line}\033[0m", file=sys.stderr)
+        _mark_notified()
+    except Exception:
+        pass

{levers9-0.2.0 → levers9-0.2.2}/src/levers9/client/client.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 import requests
 
-from ..config import get_config_context, get_settings
+from ..config import DEFAULT_API_HOST, get_config_context, get_settings
 from ..env import is_remote
 from ..exceptions import VolumeUploadError, WorkspaceNotFoundError
 from . import get, make_request
@@ -42,11 +42,25 @@ class Client:
             if not self.token:
                 self.token = config_context.token
 
+            # api_host is a dataclass default, not read from the environment, so it is 0.0.0.0 unless a
+            # caller passes one — which meant every REST call went to 0.0.0.0:1994 and only worked when the
+            # controlplane happened to be local. Prefer an explicit override, then the context the CLI and
+            # the dashboard already write, and keep the old default as the last resort.
             if not controlplane_host:
-                self.controlplane_host = settings.api_host
+                self.controlplane_host = (
+                    os.environ.get("LEVERS9_API_HOST")
+                    or (config_context.controlplane_host if settings.api_host == DEFAULT_API_HOST else settings.api_host)
+                    or settings.api_host
+                )
 
             if not controlplane_port:
-                self.controlplane_port = settings.api_port
+                override = os.environ.get("LEVERS9_API_PORT")
+                if override:
+                    self.controlplane_port = int(override)
+                elif config_context.controlplane_port == 443:
+                    self.controlplane_port = 443      # TLS front door: REST and gRPC share it
+                else:
+                    self.controlplane_port = settings.api_port
 
         if not self.tls and self.controlplane_port == 443:
             self.tls = True

{levers9-0.2.0 → levers9-0.2.2}/src/levers9/config.py

@@ -71,9 +71,19 @@ class ConfigContext:
     controlplane_host: Optional[str] = None
     controlplane_port: Optional[int] = None
 
+    # A config written before the rename spells these gateway_*. Every load comes through from_dict, and
+    # unknown keys are dropped here, so without this the old names vanish on read - and the next command
+    # that saves writes the file back with the host blank, quietly losing every context but the one in use.
+    _RENAMED = {"gateway_host": "controlplane_host", "gateway_port": "controlplane_port"}
+
     @classmethod
     def from_dict(cls, data: Mapping[str, Any]) -> "ConfigContext":
-        return cls(**{k: v for k, v in data.items() if k in inspect.signature(cls).parameters})
+        fields = inspect.signature(cls).parameters
+        out = {k: v for k, v in data.items() if k in fields}
+        for was, now in cls._RENAMED.items():
+            if data.get(was) and not out.get(now):
+                out[now] = data[was]
+        return cls(**out)
 
     def to_dict(self) -> MutableMapping[str, Any]:
         return {k: ("" if not v else v) for k, v in asdict(self).items()}

{levers9-0.2.0 → levers9-0.2.2}/src/levers9.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: levers9
-Version: 0.2.0
-Summary: levers9 SDK and CLI: run functions, endpoints, task queues, schedules, pods and GPU jobs on a levers9 cluster
+Version: 0.2.2
+Summary: levers9 SDK and CLI: run jobs, endpoints, queues, crons, boxes and GPU work on a levers9 cluster
 Author-email: Levers AI Lab <hello@uselevers.com>
 Requires-Python: <4.0,>=3.8
 Requires-Dist: typeguard<3.0.0,>=2.13.3; python_version < "3.9"

{levers9-0.2.0 → levers9-0.2.2}/src/levers9.egg-info/SOURCES.txt

@@ -76,6 +76,7 @@ src/levers9/cli/shell.py
 src/levers9/cli/skills.py
 src/levers9/cli/task.py
 src/levers9/cli/token.py
+src/levers9/cli/update_check.py
 src/levers9/cli/volume.py
 src/levers9/cli/worker.py
 src/levers9/cli/worker_management.py
@@ -139,6 +140,8 @@ src/levers9/vendor/pathspec/patterns/__init__.py
 src/levers9/vendor/pathspec/patterns/gitwildmatch.py
 tests/test_capacity.py
 tests/test_cli.py
+tests/test_client_base_url.py
+tests/test_config.py
 tests/test_container_runner.py
 tests/test_deployment.py
 tests/test_env.py
@@ -160,5 +163,6 @@ tests/test_service.py
 tests/test_shell.py
 tests/test_skills.py
 tests/test_task_queue.py
+tests/test_update_check.py
 tests/test_utils.py
 tests/test_volumes.py

levers9-0.2.2/tests/test_client_base_url.py

@@ -0,0 +1,38 @@
+"""The REST client must reach the configured controlplane, not 0.0.0.0."""
+
+import os
+import unittest
+from unittest import mock
+
+
+class BaseUrl(unittest.TestCase):
+    def _client(self, env=None, ctx_host="levers9-controlplane", ctx_port=1993):
+        from levers9.client.client import Client
+        from levers9.config import ConfigContext
+
+        with mock.patch.dict(os.environ, env or {}, clear=False), mock.patch(
+            "levers9.client.client.get_config_context",
+            return_value=ConfigContext(
+                token="t", controlplane_host=ctx_host, controlplane_port=ctx_port
+            ),
+        ), mock.patch(
+            "levers9.client.client.Client._load_workspace", lambda self: None
+        ), mock.patch("levers9.client.client.is_remote", return_value=False):
+            return Client(token="t")
+
+    def test_uses_the_configured_host_not_the_default(self):
+        c = self._client()
+        self.assertIn("levers9-controlplane", c.base_url)
+        self.assertNotIn("0.0.0.0", c.base_url)
+
+    def test_explicit_env_wins(self):
+        c = self._client(env={"LEVERS9_API_HOST": "rest.example", "LEVERS9_API_PORT": "8080"})
+        self.assertIn("rest.example:8080", c.base_url)
+
+    def test_tls_front_door_keeps_443(self):
+        c = self._client(ctx_host="levers9-grpc.uselevers.com", ctx_port=443)
+        self.assertTrue(c.base_url.startswith("https://"), c.base_url)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

levers9-0.2.2/tests/test_config.py

@@ -0,0 +1,60 @@
+"""The config file survives a round trip, including one written before the gateway -> controlplane rename."""
+
+import configparser
+from pathlib import Path
+
+from levers9.config import ConfigContext, load_config, save_config
+
+OLD_FORMAT = """\
+[default]
+token = tok-default
+gateway_host = levers9-grpc.uselevers.com
+gateway_port = 443
+
+[local]
+token = tok-local
+gateway_host = localhost
+gateway_port = 1993
+
+[staging]
+token = tok-staging
+gateway_host = staging.uselevers.com
+gateway_port = 443
+"""
+
+
+def test_old_key_names_are_read(tmp_path: Path):
+    path = tmp_path / "config"
+    path.write_text(OLD_FORMAT)
+
+    contexts = load_config(path)
+
+    assert contexts["local"].controlplane_host == "localhost"
+    # configparser hands back strings, which is what the new spelling yields too; use_ssl() takes either.
+    assert str(contexts["local"].controlplane_port) == "1993"
+    assert contexts["staging"].controlplane_host == "staging.uselevers.com"
+
+
+def test_saving_does_not_blank_the_contexts_it_did_not_touch(tmp_path: Path):
+    """The regression: unknown keys were dropped on load, so the next save wrote every host back empty."""
+    path = tmp_path / "config"
+    path.write_text(OLD_FORMAT)
+
+    contexts = load_config(path)
+    save_config(contexts, path)
+
+    parser = configparser.ConfigParser(default_section="default")
+    parser.read(path)
+
+    assert parser["local"]["controlplane_host"] == "localhost"
+    assert parser["local"]["controlplane_port"] == "1993"
+    assert parser["staging"]["controlplane_host"] == "staging.uselevers.com"
+    assert parser["staging"]["token"] == "tok-staging"
+
+
+def test_the_new_spelling_wins_when_a_config_carries_both(tmp_path: Path):
+    ctx = ConfigContext.from_dict(
+        {"token": "t", "controlplane_host": "new.example", "gateway_host": "old.example"}
+    )
+
+    assert ctx.controlplane_host == "new.example"

levers9-0.2.2/tests/test_update_check.py

@@ -0,0 +1,124 @@
+"""The behaviours that matter: never blocks, never fails a command, never nags wrongly."""
+
+import json
+import os
+import time
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from levers9.cli import update_check as uc
+
+
+class VersionCompare(unittest.TestCase):
+    def test_newer_is_detected(self):
+        for latest, installed in [
+            ("0.2.0", "0.1.272"),
+            ("1.0.0", "0.9.9"),
+            ("0.2.1", "0.2.0"),
+            ("0.10.0", "0.9.0"),
+        ]:
+            self.assertTrue(uc.is_newer(latest, installed), f"{latest} > {installed}")
+
+    def test_same_or_older_is_not(self):
+        for latest, installed in [("0.2.0", "0.2.0"), ("0.1.9", "0.2.0"), ("0.9.0", "0.10.0")]:
+            self.assertFalse(uc.is_newer(latest, installed), f"{latest} !> {installed}")
+
+    def test_prerelease_sorts_below_its_final(self):
+        self.assertFalse(uc.is_newer("0.2.0rc1", "0.2.0"))
+        self.assertTrue(uc.is_newer("0.2.0", "0.2.0rc1"))
+
+    def test_garbage_never_raises(self):
+        self.assertFalse(uc.is_newer("not-a-version", "0.1.0"))
+
+
+class Notice(unittest.TestCase):
+    def setUp(self):
+        self.tmp = Path(os.environ.get("TMPDIR", "/tmp")) / f"uc-{time.time_ns()}"
+        self.tmp.mkdir(parents=True, exist_ok=True)
+        self.patches = [
+            mock.patch.object(uc, "_cache_path", lambda: self.tmp / "update-check.json"),
+            mock.patch.object(uc, "_installed_version", lambda: "0.1.272"),
+            mock.patch.dict(os.environ, {"LEVERS9_NO_UPDATE_CHECK": "", "CI": ""}, clear=False),
+            mock.patch("sys.stderr.isatty", lambda: True),
+        ]
+        for patch in self.patches:
+            patch.start()
+
+    def tearDown(self):
+        for patch in self.patches:
+            patch.stop()
+
+    def _cache(self, latest, age_s=0):
+        (self.tmp / "update-check.json").write_text(
+            json.dumps({"latest": latest, "checked_at": time.time() - age_s})
+        )
+
+    def test_fresh_cache_with_newer_version_notifies(self):
+        self._cache("0.2.0")
+        n = uc.notice()
+        self.assertIn("0.2.0", n)
+        self.assertIn("0.1.272", n)
+        self.assertIn("upgrade", n)
+
+    def test_same_version_is_silent(self):
+        self._cache("0.1.272")
+        self.assertIsNone(uc.notice())
+
+    def test_no_cache_is_silent_and_does_not_block(self):
+        started = time.monotonic()
+        with mock.patch.object(uc, "_refresh_in_background") as bg:
+            self.assertIsNone(uc.notice())
+            bg.assert_called_once()  # refresh is scheduled for next time
+        self.assertLess(time.monotonic() - started, 0.1, "notice() must not wait on anything")
+
+    def test_stale_cache_still_uses_what_it_has(self):
+        self._cache("0.2.0", age_s=uc.CHECK_INTERVAL_S + 10)
+        with mock.patch.object(uc, "_refresh_in_background") as bg:
+            self.assertIn("0.2.0", uc.notice())
+            bg.assert_called_once()
+
+    def test_opt_out_and_ci_are_silent(self):
+        self._cache("0.2.0")
+        for var in ("LEVERS9_NO_UPDATE_CHECK", "CI"):
+            with mock.patch.dict(os.environ, {var: "1"}):
+                self.assertIsNone(uc.notice(), f"{var} should silence it")
+
+    def test_corrupt_cache_is_survivable(self):
+        (self.tmp / "update-check.json").write_text("{not json")
+        with mock.patch.object(uc, "_refresh_in_background"):
+            self.assertIsNone(uc.notice())
+
+    def test_repeats_at_most_once_a_day(self):
+        self._cache("0.2.0")
+        self.assertIsNotNone(uc.notice(), "the first look should speak")
+        uc._mark_notified()
+        self.assertIsNone(uc.notice(), "the second should not")
+
+    def test_silent_when_output_is_captured(self):
+        self._cache("0.2.0")
+        with mock.patch("sys.stderr.isatty", lambda: False):
+            self.assertIsNone(uc.notice(), "a pipe must never receive a notice")
+
+    def test_notice_goes_to_stderr_not_stdout(self):
+        import contextlib
+        import io
+
+        self._cache("0.2.0")
+        out, err = io.StringIO(), io.StringIO()
+        with contextlib.redirect_stdout(out), mock.patch("sys.stderr", err):
+            with mock.patch("sys.stderr.isatty", lambda: True, create=True):
+                uc.print_notice()
+        self.assertEqual(out.getvalue(), "", "stdout must stay clean for callers parsing it")
+
+    def test_print_notice_never_raises(self):
+        with mock.patch.object(uc, "notice", side_effect=RuntimeError("boom")):
+            uc.print_notice()  # must swallow: a notice is never worth failing a command
+
+    def test_unreachable_pypi_is_silent(self):
+        with mock.patch("urllib.request.urlopen", side_effect=OSError("no network")):
+            self.assertIsNone(uc._fetch_latest())
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)