cotop 0.2.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. {cotop-0.2.0 → cotop-0.3.0}/.github/workflows/publish.yml +2 -2
  2. {cotop-0.2.0 → cotop-0.3.0}/PKG-INFO +48 -10
  3. {cotop-0.2.0 → cotop-0.3.0}/README.md +46 -8
  4. cotop-0.3.0/SECURITY.md +23 -0
  5. {cotop-0.2.0 → cotop-0.3.0}/docs/data-sources.md +11 -7
  6. cotop-0.3.0/docs/images/dashboard.png +0 -0
  7. cotop-0.3.0/docs/images/demo.gif +0 -0
  8. cotop-0.3.0/docs/images/stop.png +0 -0
  9. {cotop-0.2.0 → cotop-0.3.0}/pyproject.toml +2 -2
  10. cotop-0.3.0/scripts/demo.tape +36 -0
  11. {cotop-0.2.0 → cotop-0.3.0}/scripts/screenshots.py +2 -1
  12. {cotop-0.2.0 → cotop-0.3.0}/src/cotop/app.py +22 -3
  13. {cotop-0.2.0 → cotop-0.3.0}/src/cotop/colab.py +20 -35
  14. cotop-0.3.0/src/cotop/colab_cli_calls.py +70 -0
  15. {cotop-0.2.0 → cotop-0.3.0}/src/cotop/model.py +16 -4
  16. {cotop-0.2.0 → cotop-0.3.0}/tests/test_app.py +120 -2
  17. cotop-0.3.0/tests/test_colab.py +79 -0
  18. cotop-0.3.0/tests/test_handoff.py +100 -0
  19. {cotop-0.2.0 → cotop-0.3.0}/tests/test_model.py +21 -0
  20. {cotop-0.2.0 → cotop-0.3.0}/uv.lock +2 -2
  21. cotop-0.2.0/docs/images/dashboard.png +0 -0
  22. cotop-0.2.0/docs/images/stop.png +0 -0
  23. cotop-0.2.0/tests/test_colab.py +0 -13
  24. {cotop-0.2.0 → cotop-0.3.0}/.gitignore +0 -0
  25. {cotop-0.2.0 → cotop-0.3.0}/LICENSE +0 -0
  26. {cotop-0.2.0 → cotop-0.3.0}/src/cotop/__init__.py +0 -0
  27. {cotop-0.2.0 → cotop-0.3.0}/src/cotop/demo.py +0 -0
  28. {cotop-0.2.0 → cotop-0.3.0}/src/cotop/widgets.py +0 -0
  29. {cotop-0.2.0 → cotop-0.3.0}/tests/__init__.py +0 -0
  30. {cotop-0.2.0 → cotop-0.3.0}/tests/fixtures/resources_g4.txt +0 -0
  31. {cotop-0.2.0 → cotop-0.3.0}/tests/test_widgets.py +0 -0
@@ -13,8 +13,8 @@ jobs:
13
13
  id-token: write # the OIDC token PyPI checks
14
14
  contents: read
15
15
  steps:
16
- - uses: actions/checkout@v4
17
- - uses: astral-sh/setup-uv@v6
16
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
17
+ - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
18
18
  - name: Tag matches the package version
19
19
  run: test "v$(uv version --short)" = "${GITHUB_REF_NAME}"
20
20
  - run: uv build
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: cotop
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: A top-like terminal dashboard for Google Colab runtimes and compute units
5
5
  Project-URL: Homepage, https://github.com/benngarcia/cotop
6
6
  Project-URL: Issues, https://github.com/benngarcia/cotop/issues
@@ -18,14 +18,14 @@ Classifier: Topic :: System :: Monitoring
18
18
  Requires-Python: >=3.12
19
19
  Requires-Dist: google-colab-cli~=0.8.0
20
20
  Requires-Dist: requests
21
- Requires-Dist: textual>=6
21
+ Requires-Dist: textual<9,>=6
22
22
  Description-Content-Type: text/markdown
23
23
 
24
24
  # cotop
25
25
 
26
26
  `top` for Google Colab: compute units, runtimes and what they cost, live in your terminal.
27
27
 
28
- ![cotop's demo account: twelve runtimes sorted by cost, compute units in red because they run out today, and a live GPU graph for the selected H100](docs/images/dashboard.png)
28
+ ![cotop --demo: moving through twelve runtimes with j, each one's live GPU graph, the ? keys panel, past sessions with h, and the stop confirmation](docs/images/demo.gif)
29
29
 
30
30
  - **Your account:** compute units left, the hourly rate, when you run out, and the rate over the last day. Compute units left turn red when they run out within a day.
31
31
  - **Runtimes:** every VM on your account, most expensive first, including ones opened in a browser, with a live GPU sparkline, rate, spend, uptime and state. A runtime idle while it bills, out of RAM or disk, or unreachable says so in its row.
@@ -49,12 +49,13 @@ cotop needs Python 3.12 or later. It is tested on macOS and should work on Linux
49
49
 
50
50
  | Key | Action |
51
51
  |---|---|
52
- | `↑` `↓` | Select a runtime |
52
+ | `↑` `↓` or `k` `j` | Select a runtime |
53
53
  | `h` | Past sessions and the hardware your account can use |
54
54
  | `r` | Refresh now (cotop also refreshes every 15 seconds) |
55
55
  | `s` | Stop the selected runtime |
56
- | `k` | Restart its kernel |
56
+ | `R` | Restart its kernel |
57
57
  | `x` | Open a shell on it with `colab ssh` |
58
+ | `?` | Show every key |
58
59
  | `q` | Quit |
59
60
 
60
61
  ![The stop confirmation, with Cancel selected](docs/images/stop.png)
@@ -74,12 +75,49 @@ Estimates start with `≈`, and upper bounds start with `≤`. Colab boots VMs b
74
75
 
75
76
  [docs/data-sources.md](docs/data-sources.md) lists each request cotop makes and what it reads.
76
77
 
77
- ## Privacy
78
+ ## What cotop can touch
78
79
 
79
- - cotop sends requests only to Google: Colab, and the account endpoint that supplies your email address.
80
- - It keeps its own files in `~/.cache/cotop`: learned rates, and balance and rate samples.
81
- - It never shows or stores tokens.
82
- - From the CLI's history it shows only event types, times and file names. It never shows code, outputs or anything typed at a prompt.
80
+ cotop signs in with the Colab CLI's own credentials, so it can do anything `colab` can, with the access you granted when you signed in. It adds no credentials of its own.
81
+
82
+ ### Guarantees
83
+
84
+ Each line is true of this release and names the test on `main` that checks it:
85
+
86
+ - Before it stops, restarts or opens a shell on a named runtime, cotop checks that the name still points at the runtime you selected (`test_every_named_action_checks_the_name_still_means_this_runtime`).
87
+ - No module in `src/cotop` other than `colab_cli_calls.py` has an import statement for `google-colab-cli`, or writes `_session` (the attribute that holds the signed-in session) as an attribute or a string literal (`test_only_the_handoff_module_imports_colab_cli_or_touches_the_session`).
88
+ - A runtime's proxy token never follows a redirect (`test_the_proxy_token_never_follows_a_redirect`).
89
+ - From the CLI's history, cotop never shows code, outputs or prompt replies (`test_history_never_surfaces_code_outputs_or_stdin`).
90
+
91
+ ### What cotop does in this release
92
+
93
+ - It sends GET requests through the CLI's signed-in session: to `colab.research.google.com` for the balance and the runtime list, and to Google's userinfo endpoint for your email address.
94
+ - It sends GET requests to each runtime's proxy, at the URL Colab returns for it, with that runtime's proxy token.
95
+ - It reads the CLI's history files in `~/.config/colab-cli/history/` and the CLI's session list.
96
+ - It writes learned rates and balance samples to `~/.cache/cotop/`.
97
+ - For a runtime the CLI started, it runs `colab stop -s NAME` or `colab restart-kernel -s NAME` when you press `s` or `R` and confirm, and `colab ssh -s NAME [-i KEY]` in your terminal when you press `x`.
98
+ - `cotop --demo` returns from `main()` before `sign_in` and runs on the made-up account in `src/cotop/demo.py`, with its cache in a temporary directory (`run_demo`).
99
+
100
+ [docs/data-sources.md](docs/data-sources.md) gives each request and how often cotop sends it.
101
+
102
+ ### Calls into the Colab CLI
103
+
104
+ `src/cotop/colab_cli_calls.py` hands these calls to `google-colab-cli`:
105
+
106
+ - `sign_in` calls the CLI's `get_credentials()` at start. It returns a `Google`, which keeps the session private and offers two calls:
107
+ - `Google.get` sends a GET through the session. When the session's access token expires, the session refreshes it with a POST.
108
+ - `Google.unassign` calls the CLI client's `unassign`, to stop a runtime the CLI didn't start.
109
+ - `named_sessions` calls the CLI's `StateStore(path).list()`, once `~/.config/colab-cli/sessions.json` exists.
110
+ - `colab_argv` builds the `colab` command lines described above.
111
+
112
+ What these calls read, write and send inside the CLI is the CLI's behavior.
113
+
114
+ ### What the CLI does (0.8.0; not a complete list)
115
+
116
+ These examples are taken from [google-colab-cli 0.8.0](https://pypi.org/project/google-colab-cli/0.8.0/):
117
+
118
+ - `get_credentials()` reads and writes the OS keyring. It moves an old plaintext `~/.config/colab-cli/token.json` into the keyring, and reads `~/.colab-cli-oauth-config.json` if that file exists.
119
+ - The three `colab` commands cotop runs log to `~/.config/colab-cli/colab.log` with secrets redacted, update files under `~/.config/colab-cli/`, and check `pypi.org` for an update at most once a day.
120
+ - `colab ssh` reads your SSH public key.
83
121
 
84
122
  ## Not affiliated with Google
85
123
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  `top` for Google Colab: compute units, runtimes and what they cost, live in your terminal.
4
4
 
5
- ![cotop's demo account: twelve runtimes sorted by cost, compute units in red because they run out today, and a live GPU graph for the selected H100](docs/images/dashboard.png)
5
+ ![cotop --demo: moving through twelve runtimes with j, each one's live GPU graph, the ? keys panel, past sessions with h, and the stop confirmation](docs/images/demo.gif)
6
6
 
7
7
  - **Your account:** compute units left, the hourly rate, when you run out, and the rate over the last day. Compute units left turn red when they run out within a day.
8
8
  - **Runtimes:** every VM on your account, most expensive first, including ones opened in a browser, with a live GPU sparkline, rate, spend, uptime and state. A runtime idle while it bills, out of RAM or disk, or unreachable says so in its row.
@@ -26,12 +26,13 @@ cotop needs Python 3.12 or later. It is tested on macOS and should work on Linux
26
26
 
27
27
  | Key | Action |
28
28
  |---|---|
29
- | `↑` `↓` | Select a runtime |
29
+ | `↑` `↓` or `k` `j` | Select a runtime |
30
30
  | `h` | Past sessions and the hardware your account can use |
31
31
  | `r` | Refresh now (cotop also refreshes every 15 seconds) |
32
32
  | `s` | Stop the selected runtime |
33
- | `k` | Restart its kernel |
33
+ | `R` | Restart its kernel |
34
34
  | `x` | Open a shell on it with `colab ssh` |
35
+ | `?` | Show every key |
35
36
  | `q` | Quit |
36
37
 
37
38
  ![The stop confirmation, with Cancel selected](docs/images/stop.png)
@@ -51,12 +52,49 @@ Estimates start with `≈`, and upper bounds start with `≤`. Colab boots VMs b
51
52
 
52
53
  [docs/data-sources.md](docs/data-sources.md) lists each request cotop makes and what it reads.
53
54
 
54
- ## Privacy
55
+ ## What cotop can touch
55
56
 
56
- - cotop sends requests only to Google: Colab, and the account endpoint that supplies your email address.
57
- - It keeps its own files in `~/.cache/cotop`: learned rates, and balance and rate samples.
58
- - It never shows or stores tokens.
59
- - From the CLI's history it shows only event types, times and file names. It never shows code, outputs or anything typed at a prompt.
57
+ cotop signs in with the Colab CLI's own credentials, so it can do anything `colab` can, with the access you granted when you signed in. It adds no credentials of its own.
58
+
59
+ ### Guarantees
60
+
61
+ Each line is true of this release and names the test on `main` that checks it:
62
+
63
+ - Before it stops, restarts or opens a shell on a named runtime, cotop checks that the name still points at the runtime you selected (`test_every_named_action_checks_the_name_still_means_this_runtime`).
64
+ - No module in `src/cotop` other than `colab_cli_calls.py` has an import statement for `google-colab-cli`, or writes `_session` (the attribute that holds the signed-in session) as an attribute or a string literal (`test_only_the_handoff_module_imports_colab_cli_or_touches_the_session`).
65
+ - A runtime's proxy token never follows a redirect (`test_the_proxy_token_never_follows_a_redirect`).
66
+ - From the CLI's history, cotop never shows code, outputs or prompt replies (`test_history_never_surfaces_code_outputs_or_stdin`).
67
+
68
+ ### What cotop does in this release
69
+
70
+ - It sends GET requests through the CLI's signed-in session: to `colab.research.google.com` for the balance and the runtime list, and to Google's userinfo endpoint for your email address.
71
+ - It sends GET requests to each runtime's proxy, at the URL Colab returns for it, with that runtime's proxy token.
72
+ - It reads the CLI's history files in `~/.config/colab-cli/history/` and the CLI's session list.
73
+ - It writes learned rates and balance samples to `~/.cache/cotop/`.
74
+ - For a runtime the CLI started, it runs `colab stop -s NAME` or `colab restart-kernel -s NAME` when you press `s` or `R` and confirm, and `colab ssh -s NAME [-i KEY]` in your terminal when you press `x`.
75
+ - `cotop --demo` returns from `main()` before `sign_in` and runs on the made-up account in `src/cotop/demo.py`, with its cache in a temporary directory (`run_demo`).
76
+
77
+ [docs/data-sources.md](docs/data-sources.md) gives each request and how often cotop sends it.
78
+
79
+ ### Calls into the Colab CLI
80
+
81
+ `src/cotop/colab_cli_calls.py` hands these calls to `google-colab-cli`:
82
+
83
+ - `sign_in` calls the CLI's `get_credentials()` at start. It returns a `Google`, which keeps the session private and offers two calls:
84
+ - `Google.get` sends a GET through the session. When the session's access token expires, the session refreshes it with a POST.
85
+ - `Google.unassign` calls the CLI client's `unassign`, to stop a runtime the CLI didn't start.
86
+ - `named_sessions` calls the CLI's `StateStore(path).list()`, once `~/.config/colab-cli/sessions.json` exists.
87
+ - `colab_argv` builds the `colab` command lines described above.
88
+
89
+ What these calls read, write and send inside the CLI is the CLI's behavior.
90
+
91
+ ### What the CLI does (0.8.0; not a complete list)
92
+
93
+ These examples are taken from [google-colab-cli 0.8.0](https://pypi.org/project/google-colab-cli/0.8.0/):
94
+
95
+ - `get_credentials()` reads and writes the OS keyring. It moves an old plaintext `~/.config/colab-cli/token.json` into the keyring, and reads `~/.colab-cli-oauth-config.json` if that file exists.
96
+ - The three `colab` commands cotop runs log to `~/.config/colab-cli/colab.log` with secrets redacted, update files under `~/.config/colab-cli/`, and check `pypi.org` for an update at most once a day.
97
+ - `colab ssh` reads your SSH public key.
60
98
 
61
99
  ## Not affiliated with Google
62
100
 
@@ -0,0 +1,23 @@
1
+ # Security
2
+
3
+ cotop runs with your Colab CLI sign-in, so a bug in it could expose that token
4
+ or act on a runtime you didn't choose. The README's
5
+ [guarantees](README.md#guarantees) say what cotop's code holds to, each with the
6
+ test on `main` that checks it.
7
+
8
+ ## Scope
9
+
10
+ In scope is cotop's own code. Examples:
11
+ - a token reaching the screen, the cache, or a host other than the one Colab returned;
12
+ - an action on a runtime other than the one you chose.
13
+
14
+ Behavior inside `google-colab-cli` or the `colab` command belongs to that
15
+ project.
16
+
17
+ ## Reporting a vulnerability
18
+
19
+ Don't put details in a public issue. Report it privately through
20
+ [GitHub's form](https://github.com/benngarcia/cotop/security/advisories/new),
21
+ which goes to the maintainer instead of the public.
22
+
23
+ Fixes go into the latest release on PyPI.
@@ -1,9 +1,13 @@
1
1
  # Where cotop's numbers come from
2
2
 
3
- cotop polls the account, the runtime list and each runtime's kernels every 15
4
- seconds, and each runtime's resources every 2 seconds for the graphs. Watching
5
- sends only GET requests. Stop sends a POST: the colab CLI's own `colab stop`,
6
- or for a runtime the CLI didn't start, the CLI client's `unassign` call.
3
+ cotop polls the account, the runtime list and each runtime's kernels at a
4
+ 15-second interval, on `r` and after each action, and each runtime's resources
5
+ at a 2-second interval for the graphs. In this release those requests are GETs. The Colab
6
+ CLI's signed-in session refreshes its access token with a POST when it expires.
7
+ Stop sends a POST: the colab CLI's own `colab stop`, or for a runtime the CLI
8
+ didn't start, the CLI client's `unassign` call. The README's
9
+ [What cotop can touch](../README.md#what-cotop-can-touch) lists the guarantees
10
+ and the calls cotop makes into the CLI.
7
11
 
8
12
  `cotop --demo` runs on `src/cotop/demo.py`, a made-up account, and sends no
9
13
  requests at all.
@@ -13,10 +17,10 @@ requests at all.
13
17
  | Account email | `openidconnect.googleapis.com/v1/userinfo` | Signed in with the Colab CLI's OAuth token from the OS keyring |
14
18
  | Balance, rate, eligible hardware | `colab.research.google.com/tun/m/ccu-info` | The same call as `colab usage`. The CLI drops `eligibleGpus` and `eligibleTpus`; cotop reads the raw body |
15
19
  | Runtimes | `/tun/m/assignments` | Every VM the account holds, including ones opened in a browser. These show as *untracked* |
16
- | Runtime names, running command | `~/.config/colab-cli/sessions.json` | Read under the CLI's file lock and joined on `endpoint`. cotop never prunes or rewrites this file, which `colab sessions` and `colab status` do |
20
+ | Runtime names, running command | `~/.config/colab-cli/sessions.json` | Read under the CLI's file lock and joined on `endpoint`. `colab sessions` and `colab status` prune and rewrite this file, and `colab stop`, which cotop runs on `s`, updates it |
17
21
  | Kernel state, idle time, clients | Runtime proxy `/api/kernels`, `/api/status` | Requests carry `?no_track_activity=1` |
18
22
  | GPU, VRAM, RAM, disk | Runtime proxy `/api/colab/resources`, every 2 s | The same endpoint the Colab VS Code extension uses. The body has an XSSI prefix. Values change every second; a read takes about 0.4 s. A read that fails or takes over 3 s is a gap in the graph, never a zero |
19
- | Assignment time, recent events, past sessions | `~/.config/colab-cli/history/*.jsonl` | Only event types, times and file names are shown. Code, outputs and stdin replies are never shown |
23
+ | Assignment time, recent events, past sessions | `~/.config/colab-cli/history/*.jsonl` | Code, outputs and prompt replies are not shown; see the README's guarantees |
20
24
 
21
25
  ## Estimates
22
26
 
@@ -68,7 +72,7 @@ idle activity.
68
72
  | Key | Runs | Notes |
69
73
  |---|---|---|
70
74
  | `s` | `colab stop -s NAME` | For an untracked runtime, the CLI's `Client.unassign(endpoint)`, because no name exists |
71
- | `k` | `colab restart-kernel -s NAME` | Only for runtimes the CLI started |
75
+ | `R` | `colab restart-kernel -s NAME` | Only for runtimes the CLI started |
72
76
  | `x` | `colab ssh -s NAME [-i KEY]` | The dashboard suspends while the shell runs. A failed connection waits for Enter so its error stays readable |
73
77
 
74
78
  The CLI resolves names, not endpoints. Before a named action, cotop reads
Binary file
Binary file
Binary file
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "cotop"
3
- version = "0.2.0"
3
+ version = "0.3.0"
4
4
  description = "A top-like terminal dashboard for Google Colab runtimes and compute units"
5
5
  readme = "README.md"
6
6
  license = "Apache-2.0"
@@ -21,7 +21,7 @@ dependencies = [
21
21
  # cotop reads the CLI's internals (auth, session file, client), so it pins the minor version.
22
22
  "google-colab-cli~=0.8.0",
23
23
  "requests",
24
- "textual>=6",
24
+ "textual>=6,<9", # 6.0 and 8.2 tested; 9 may change the DataTable and screen APIs cotop uses
25
25
  ]
26
26
 
27
27
  [project.urls]
@@ -0,0 +1,36 @@
1
+ # Records docs/images/demo.gif from `cotop --demo`; nothing here touches a Colab account.
2
+ # Run from the repo root: vhs scripts/demo.tape (it syncs the environment itself,
3
+ # and fails without writing the GIF if cotop doesn't start).
4
+ Output docs/images/demo.gif
5
+ Set Shell "bash"
6
+ Set FontSize 15
7
+ Set Width 1360
8
+ Set Height 820
9
+ Set Padding 12
10
+ Set Framerate 12
11
+ Set TypingSpeed 0
12
+
13
+ Hide
14
+ Type "export PS1='$ ' && uv sync -q && clear && echo synced" Enter
15
+ Wait+Screen@180s /^synced/
16
+ Type "uv run --no-sync cotop --demo" Enter
17
+ Wait+Screen@30s /compute units left/
18
+ Sleep 1s
19
+ Show
20
+ Sleep 3s
21
+ Type "j" Sleep 1.2s
22
+ Type "j" Sleep 1.2s
23
+ Type "j" Sleep 1.2s
24
+ Type "j" Sleep 2.5s
25
+ Type "j" Sleep 1.2s
26
+ Type "j" Sleep 1.2s
27
+ Type "j" Sleep 2.5s
28
+ Type "?" Sleep 3s
29
+ Type "?" Sleep 1s
30
+ Type "h" Sleep 4s
31
+ Escape Sleep 1s
32
+ Type "k" Sleep 1s
33
+ Type "s" Sleep 3s
34
+ Type "n" Sleep 2s
35
+ Hide
36
+ Type "q"
@@ -1,4 +1,5 @@
1
- """Render the README screenshots from the demo account; no Colab account is touched.
1
+ """Render the README screenshots from the demo account; no Colab account is touched. The GIF comes from
2
+ scripts/demo.tape: `vhs scripts/demo.tape`.
2
3
 
3
4
  uv run python scripts/screenshots.py OUT_DIR
4
5
 
@@ -17,7 +17,7 @@ from textual.containers import Horizontal, Vertical
17
17
  from textual.screen import ModalScreen, Screen
18
18
  from textual.theme import Theme
19
19
  from textual.widgets import Button, DataTable, Footer, Label, Static
20
- from textual.worker import Worker
20
+ from textual.worker import Worker, WorkerState
21
21
 
22
22
  from cotop.colab import Colab
23
23
  from cotop.model import (
@@ -229,6 +229,10 @@ class Runtimes(DataTable):
229
229
  """The list to pick from, most expensive first; the GPU column moves every two seconds."""
230
230
 
231
231
  COLUMNS = ("Name", "Hardware", "GPU", "CU/hr", "Spent", "State")
232
+ BINDINGS = [
233
+ Binding("j", "cursor_down", "Down", show=False),
234
+ Binding("k", "cursor_up", "Up", show=False),
235
+ ]
232
236
  WIDE = 100 # below this many columns "Up" is dropped; the panel still shows it
233
237
 
234
238
  def on_mount(self) -> None:
@@ -404,9 +408,10 @@ class Dashboard(App):
404
408
  BINDINGS = [
405
409
  ("r", "refresh", "Refresh"),
406
410
  ("s", "stop", "Stop"),
407
- ("k", "restart_kernel", "Restart kernel"),
411
+ ("R", "restart_kernel", "Restart kernel"),
408
412
  ("x", "ssh", "SSH"),
409
413
  ("h", "history", "History"),
414
+ Binding("question_mark", "keys", "Keys"),
410
415
  Binding("q", "quit", "Quit"),
411
416
  ]
412
417
 
@@ -419,6 +424,7 @@ class Dashboard(App):
419
424
  self.email: str | None = None
420
425
  self.snapshot: Snapshot | None = None
421
426
  self.polling: Worker | None = None
427
+ self.refresh_pending = False # asked for while a poll ran, which may predate the change
422
428
  self.sampling: Worker | None = None
423
429
 
424
430
  def compose(self) -> ComposeResult:
@@ -440,9 +446,14 @@ class Dashboard(App):
440
446
  # Polling: the account and kernel status every 15 s, resources every 2 s.
441
447
 
442
448
  def action_refresh(self) -> None:
443
- if not (self.polling and self.polling.is_running):
449
+ self.refresh_pending = bool(self.polling and self.polling.is_running)
450
+ if not self.refresh_pending:
444
451
  self.polling = self.poll()
445
452
 
453
+ def on_worker_state_changed(self, event: Worker.StateChanged) -> None:
454
+ if event.worker is self.polling and event.state == WorkerState.SUCCESS and self.refresh_pending:
455
+ self.action_refresh()
456
+
446
457
  def action_sample(self) -> None:
447
458
  if self.snapshot and not (self.sampling and self.sampling.is_running):
448
459
  self.sampling = self.sample(self.snapshot.runtimes)
@@ -551,6 +562,13 @@ class Dashboard(App):
551
562
  return False
552
563
  return True
553
564
 
565
+ def action_keys(self) -> None:
566
+ """Toggle Textual's panel of every key that works here."""
567
+ if self.screen.query("HelpPanel"):
568
+ self.action_hide_help_panel()
569
+ else:
570
+ self.action_show_help_panel()
571
+
554
572
  def action_history(self) -> None:
555
573
  if self.snapshot:
556
574
  self.push_screen(HistoryScreen(self.snapshot, self.rates))
@@ -573,6 +591,7 @@ class Dashboard(App):
573
591
  argv = self.colab.ssh_command(runtime)
574
592
  except Exception as e:
575
593
  self.call_from_thread(self.notify, f"{runtime.name}: {e}", severity="error", timeout=10)
594
+ self.call_from_thread(self.action_refresh)
576
595
  return
577
596
  self.call_from_thread(self.run_in_terminal, argv)
578
597
 
@@ -10,15 +10,13 @@ from __future__ import annotations
10
10
 
11
11
  import logging
12
12
  import subprocess
13
- import sys
14
13
  from concurrent.futures import ThreadPoolExecutor
15
14
  from pathlib import Path
16
15
 
17
16
  import requests
18
- from colab_cli.auth import get_credentials
19
- from colab_cli.client import Client, Prod
20
- from colab_cli.state import StateStore
21
17
 
18
+ from cotop.colab_cli_calls import Command, Google, colab_argv, named_sessions
19
+ from cotop.colab_cli_calls import sign_in as cli_sign_in
22
20
  from cotop.model import History, Resources, Runtime, Status, parse_json, utc_now
23
21
 
24
22
  COLAB = "https://colab.research.google.com"
@@ -27,26 +25,23 @@ HEADERS = {"Accept": "application/json", "X-Colab-Client-Agent": "colab-cli"}
27
25
  TIMEOUT = 15
28
26
  RESOURCES_TIMEOUT = 3 # readings come every 2 s; one later than that is a gap
29
27
  CLI_HOME = Path("~/.config/colab-cli").expanduser()
28
+ SESSIONS = CLI_HOME / "sessions.json"
30
29
 
31
- # The CLI's client logs request headers and bodies at DEBUG; keep tokens out.
32
- logging.getLogger("colab_cli").setLevel(logging.WARNING)
33
30
  logging.getLogger("urllib3").setLevel(logging.WARNING)
34
31
 
35
32
 
36
33
  class Colab:
37
- def __init__(self, session, ssh_identity: str | None = None):
38
- self.session = session
34
+ def __init__(self, google: Google | None, ssh_identity: str | None = None):
35
+ self.google = google
39
36
  self.ssh_identity = ssh_identity
40
37
 
41
38
  @classmethod
42
39
  def sign_in(cls, ssh_identity: str | None = None) -> Colab:
43
40
  """Use the token the colab CLI stored; prompts for sign-in if there is none."""
44
- return cls(get_credentials(), ssh_identity)
41
+ return cls(cli_sign_in(), ssh_identity)
45
42
 
46
43
  def _get(self, url: str, **params):
47
- r = self.session.get(url, params=params, headers=HEADERS, timeout=TIMEOUT)
48
- r.raise_for_status()
49
- return parse_json(r.text)
44
+ return parse_json(self.google.get(url, params=params, headers=HEADERS, timeout=TIMEOUT))
50
45
 
51
46
  def email(self) -> str:
52
47
  return self._get(USERINFO)["email"]
@@ -59,19 +54,18 @@ class Colab:
59
54
 
60
55
  def stop(self, runtime: Runtime) -> str:
61
56
  if runtime.name is None: # opened in a browser or on another host: no CLI name to stop
62
- Client(Prod(), self.session).unassign(runtime.endpoint)
57
+ self.google.unassign(runtime.endpoint)
63
58
  return f"Stopped {runtime.endpoint}."
64
59
  self.confirm_still_assigned(runtime)
65
- return _cli("stop", "-s", runtime.name)
60
+ return _cli("stop", runtime.name)
66
61
 
67
62
  def restart_kernel(self, runtime: Runtime) -> str:
68
63
  self.confirm_still_assigned(runtime)
69
- return _cli("restart-kernel", "-s", runtime.name)
64
+ return _cli("restart-kernel", runtime.name)
70
65
 
71
66
  def ssh_command(self, runtime: Runtime) -> list[str]:
72
67
  self.confirm_still_assigned(runtime)
73
- identity = ["-i", self.ssh_identity] if self.ssh_identity else []
74
- return [_colab(), "ssh", "-s", runtime.name, *identity]
68
+ return colab_argv("ssh", runtime.name, self.ssh_identity)
75
69
 
76
70
  def confirm_still_assigned(self, runtime: Runtime) -> None:
77
71
  """Act on a name only while it still means this VM.
@@ -84,11 +78,7 @@ class Colab:
84
78
  raise RuntimeGone(f"{runtime.name or runtime.endpoint} is no longer this runtime; refresh and retry")
85
79
 
86
80
  def sessions(self) -> dict[str, dict]:
87
- """The CLI's named sessions, without their tokens, read under the CLI's own lock."""
88
- return {
89
- name: {"name": s.name, "endpoint": s.endpoint, "running": s.running}
90
- for name, s in StateStore().list().items()
91
- }
81
+ return named_sessions(SESSIONS)
92
82
 
93
83
  def history(self) -> History:
94
84
  return History.load(CLI_HOME / "history")
@@ -116,28 +106,23 @@ def still_assigned(runtime: Runtime, assignments: list[dict], local: dict[str, d
116
106
  return runtime.endpoint in live and local.get(runtime.name, {}).get("endpoint") == runtime.endpoint
117
107
 
118
108
 
119
- def _colab() -> str:
120
- """The colab CLI installed with cotop, so it matches the library cotop reads with."""
121
- path = Path(sys.executable).with_name("colab")
122
- if not path.exists():
123
- raise FileNotFoundError(f"the colab CLI is missing beside {sys.executable}")
124
- return str(path)
125
-
126
-
127
- def _cli(*args: str) -> str:
109
+ def _cli(command: Command, name: str) -> str:
128
110
  """Run a colab CLI command; its last output line is the result to show."""
129
- done = subprocess.run([_colab(), *args], capture_output=True, text=True, timeout=180)
111
+ done = subprocess.run(colab_argv(command, name), capture_output=True, text=True, timeout=180)
130
112
  lines = (done.stdout + done.stderr).strip().splitlines()
131
113
  if done.returncode != 0:
132
- raise RuntimeError(lines[-1] if lines else f"colab {args[0]} exited {done.returncode}")
133
- return lines[-1] if lines else f"colab {args[0]} done"
114
+ raise RuntimeError(lines[-1] if lines else f"colab {command} exited {done.returncode}")
115
+ return lines[-1] if lines else f"colab {command} done"
134
116
 
135
117
 
136
118
  def _proxy_get(url: str, token: str, path: str, timeout: float):
137
119
  headers = {**HEADERS, "X-Colab-Runtime-Proxy-Token": token}
138
120
  # Jupyter Server skips activity tracking for this parameter; whether Colab's
139
121
  # idle shutdown looks at it is not documented.
140
- r = requests.get(url.rstrip("/") + path, headers=headers, params={"no_track_activity": "1"}, timeout=timeout)
122
+ # The token is for this runtime's proxy only, so a redirect is an error, never followed.
123
+ r = requests.get(url.rstrip("/") + path, headers=headers, params={"no_track_activity": "1"}, timeout=timeout, allow_redirects=False)
124
+ if r.is_redirect:
125
+ raise requests.HTTPError(f"runtime proxy redirected to {r.headers.get('Location', '?')}", response=r)
141
126
  r.raise_for_status()
142
127
  return parse_json(r.text)
143
128
 
@@ -0,0 +1,70 @@
1
+ """Every call cotop makes into google-colab-cli. No other cotop module imports colab_cli.
2
+
3
+ tests/test_handoff.py pins what it exports and the command lines it builds.
4
+ What these calls do inside the CLI is the CLI's behavior; this file is where
5
+ cotop decides what to hand it.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import logging
11
+ import sys
12
+ from pathlib import Path
13
+ from typing import Literal, get_args
14
+
15
+ from colab_cli.auth import get_credentials
16
+ from colab_cli.client import Client, Prod
17
+ from colab_cli.state import StateStore
18
+
19
+ __all__ = ["Command", "Google", "colab_argv", "named_sessions", "sign_in"]
20
+
21
+ Command = Literal["stop", "restart-kernel", "ssh"]
22
+
23
+ # The CLI's client logs request headers and bodies at DEBUG; keep tokens out of cotop's process.
24
+ logging.getLogger("colab_cli").setLevel(logging.WARNING)
25
+
26
+
27
+ class Google:
28
+ """The CLI's signed-in session, as cotop may use it: GET, and stop a runtime."""
29
+
30
+ def __init__(self, session):
31
+ self._session = session
32
+
33
+ def get(self, url: str, *, params: dict, headers: dict, timeout: float) -> str:
34
+ r = self._session.get(url, params=params, headers=headers, timeout=timeout)
35
+ r.raise_for_status()
36
+ return r.text
37
+
38
+ def unassign(self, endpoint: str) -> None:
39
+ Client(Prod(), self._session).unassign(endpoint)
40
+
41
+
42
+ def sign_in() -> Google:
43
+ """The CLI's own sign-in; it prompts in the terminal if it has no token."""
44
+ return Google(get_credentials())
45
+
46
+
47
+ def named_sessions(path: Path) -> dict[str, dict]:
48
+ """The CLI's named sessions, without their tokens, read under the CLI's own lock.
49
+
50
+ None until the CLI first writes the file: before then its store fails,
51
+ creating its lock before the directory the lock goes in.
52
+ """
53
+ if not path.exists():
54
+ return {}
55
+ return {
56
+ name: {"name": s.name, "endpoint": s.endpoint, "running": s.running}
57
+ for name, s in StateStore(str(path)).list().items()
58
+ }
59
+
60
+
61
+ def colab_argv(command: Command, name: str, identity: str | None = None) -> list[str]:
62
+ """The whole command line for the colab CLI installed with cotop, which matches the library above."""
63
+ if command not in get_args(Command):
64
+ raise ValueError(f"cotop does not run `colab {command}`")
65
+ if identity and command != "ssh":
66
+ raise ValueError(f"`colab {command}` takes no SSH key")
67
+ path = Path(sys.executable).with_name("colab")
68
+ if not path.exists():
69
+ raise FileNotFoundError(f"the colab CLI is missing beside {sys.executable}")
70
+ return [str(path), command, "-s", name, *(["-i", identity] if identity else [])]
@@ -410,10 +410,8 @@ class History:
410
410
 
411
411
  @classmethod
412
412
  def load(cls, directory: Path) -> History:
413
- events = {}
414
- for f in directory.glob("*.jsonl"):
415
- events[f.stem] = [json.loads(l) for l in f.read_text().splitlines() if l.strip()]
416
- return cls(events)
413
+ """Lines cotop can't read are skipped: the CLI may be halfway through writing the last one."""
414
+ return cls({f.stem: [e for l in f.read_text(errors="replace").splitlines() if (e := _event(l))] for f in directory.glob("*.jsonl")})
417
415
 
418
416
  def assigned_at(self) -> dict[str, datetime]:
419
417
  """When the CLI was handed each endpoint."""
@@ -453,6 +451,20 @@ class History:
453
451
  return sorted(sessions, key=lambda s: s.created, reverse=True)
454
452
 
455
453
 
454
+ EVENT_FIELDS = {"session_created": {"endpoint", "accelerator", "machine_shape"}} # what History reads beyond the type and time
455
+
456
+
457
+ def _event(line: str) -> dict | None:
458
+ """One history line, if it is an event with the fields History reads."""
459
+ try:
460
+ e = json.loads(line)
461
+ if isinstance(e["event_type"], str) and parse_time(e["timestamp"]).tzinfo and EVENT_FIELDS.get(e["event_type"], set()) <= e.keys():
462
+ return e
463
+ except (ValueError, TypeError, KeyError, AttributeError):
464
+ pass
465
+ return None
466
+
467
+
456
468
  def _past(name: str, created: dict, ended: dict | None) -> PastSession:
457
469
  hardware = "CPU" if created["accelerator"] == "NONE" else created["accelerator"]
458
470
  return PastSession(
@@ -133,7 +133,7 @@ async def test_kernel_and_ssh_actions_refuse_untracked_runtimes(isolated):
133
133
  app = Dashboard(colab, isolated)
134
134
  async with app.run_test(size=(150, 46)) as pilot:
135
135
  await settle(app, pilot)
136
- await pilot.press("k", "x")
136
+ await pilot.press("R", "x")
137
137
  await pilot.pause()
138
138
  assert colab.calls == [] and len(app._notifications) == 2
139
139
  assert app.screen is app.screen_stack[0]
@@ -251,7 +251,7 @@ async def test_runtime_keys_do_nothing_on_the_history_screen(isolated):
251
251
  app = Dashboard(colab, isolated)
252
252
  async with app.run_test(size=(150, 46)) as pilot:
253
253
  await settle(app, pilot)
254
- await pilot.press("h", "x", "s", "k")
254
+ await pilot.press("h", "x", "s", "R")
255
255
  await settle(app, pilot)
256
256
  assert type(app.screen).__name__ == "HistoryScreen"
257
257
  assert colab.calls == []
@@ -290,3 +290,121 @@ def balance_is_red(app) -> bool:
290
290
  span = next(s for s in text.spans if text.plain[s.start:s.end].startswith("5,227"))
291
291
  color = Style.parse(str(span.style)).color
292
292
  return color is not None and color.get_truecolor() == RichColor.parse(RED).get_truecolor()
293
+
294
+
295
+ async def test_vim_keys_move_and_restart_needs_shift_r(isolated):
296
+ colab = StubColab([G4, T4], {G4["endpoint"]: status(), T4["endpoint"]: status()}, {}, rate=11.89)
297
+ app = Dashboard(colab, isolated)
298
+ async with app.run_test(size=(150, 46)) as pilot:
299
+ await settle(app, pilot)
300
+ table = app.query_one(Runtimes)
301
+ await pilot.press("j")
302
+ assert table.cursor_row == 1
303
+ await pilot.press("k")
304
+ assert table.cursor_row == 0 and app.screen is app.screen_stack[0] # k moves; it no longer restarts
305
+ await pilot.press("R")
306
+ assert "Restart train's kernel?" in str(app.screen.query_one("Label").render())
307
+ await pilot.press("n", "question_mark")
308
+ assert app.screen.query("HelpPanel")
309
+ await pilot.press("question_mark")
310
+ assert not app.screen.query("HelpPanel")
311
+
312
+
313
+ async def test_a_failed_ssh_refreshes_like_any_other_action(isolated):
314
+ """x on a stale name fails, and the list must not stay stale until the next tick."""
315
+ colab = StubColab([G4], {G4["endpoint"]: status()}, {}, rate=11.89)
316
+ polls = []
317
+ assignments = colab.assignments
318
+ colab.assignments = lambda: polls.append(1) or assignments()
319
+
320
+ def ssh_command(runtime):
321
+ raise RuntimeError("train is no longer this runtime; refresh and retry")
322
+
323
+ colab.ssh_command = ssh_command
324
+ app = Dashboard(colab, isolated)
325
+ async with app.run_test(size=(150, 46)) as pilot:
326
+ await settle(app, pilot)
327
+ before = len(polls)
328
+ await pilot.press("x")
329
+ await settle(app, pilot)
330
+ assert len(polls) == before + 1
331
+
332
+
333
+ async def test_the_demo_connects_to_nothing_and_runs_nothing(tmp_path, monkeypatch):
334
+ import socket
335
+ import subprocess
336
+
337
+ from cotop.app import demo_dashboard
338
+
339
+ attempts = []
340
+ monkeypatch.setattr(socket.socket, "connect", lambda self, *a: attempts.append(("connect", a)))
341
+ monkeypatch.setattr(subprocess, "run", lambda *a, **k: attempts.append(("run", a)))
342
+ monkeypatch.setattr(subprocess, "Popen", lambda *a, **k: attempts.append(("popen", a)))
343
+ app = demo_dashboard(tmp_path)
344
+ async with app.run_test(size=(150, 46)) as pilot:
345
+ await settle(app, pilot)
346
+ await pilot.press("s", "y", "R", "y", "x", "h", "escape", "r")
347
+ await settle(app, pilot)
348
+ assert attempts == []
349
+
350
+
351
+ async def test_ssh_runs_the_command_line_unchanged(isolated, monkeypatch):
352
+ import contextlib
353
+
354
+ import cotop.app
355
+
356
+ colab = StubColab([G4], {G4["endpoint"]: status()}, {}, rate=11.89)
357
+ expected = ["/venv/bin/colab", "ssh", "-s", "train"]
358
+ colab.ssh_command = lambda runtime: list(expected) # a fresh list, so a change made in place shows
359
+ ran = []
360
+ monkeypatch.setattr(cotop.app.subprocess, "run", lambda a, **k: ran.append(list(a)) or type("Done", (), {"returncode": 0})())
361
+ app = Dashboard(colab, isolated)
362
+ monkeypatch.setattr(app, "suspend", contextlib.nullcontext)
363
+ async with app.run_test(size=(150, 46)) as pilot:
364
+ await settle(app, pilot)
365
+ await pilot.press("x")
366
+ await settle(app, pilot)
367
+ assert ran == [expected]
368
+
369
+
370
+ async def test_a_refresh_asked_for_during_a_poll_runs_after_it(isolated):
371
+ """A stop that lands while a poll is reading must not wait for the next 15 s tick."""
372
+ import threading
373
+
374
+ colab = StubColab([G4, T4], {G4["endpoint"]: status(), T4["endpoint"]: status()}, {}, rate=11.89)
375
+ gate, polls = threading.Event(), []
376
+ assignments = colab.assignments
377
+
378
+ def slow_assignments():
379
+ polls.append(1)
380
+ if len(polls) == 2:
381
+ gate.wait(5) # the second poll is still reading when the stop finishes
382
+ return assignments()
383
+
384
+ colab.assignments = slow_assignments
385
+ app = Dashboard(colab, isolated)
386
+ async with app.run_test(size=(150, 46)) as pilot:
387
+ await settle(app, pilot)
388
+ app.action_refresh() # poll 2, held at the gate
389
+ await pilot.pause()
390
+ await pilot.press("s", "y") # its refresh arrives while poll 2 runs
391
+ await pilot.pause(0.3)
392
+ gate.set()
393
+ await settle(app, pilot)
394
+ assert len(polls) == 3
395
+ assert colab.calls == [("stop", G4["endpoint"])]
396
+
397
+
398
+ def test_the_demo_signs_in_to_nothing_and_leaves_the_cache_alone(tmp_path, monkeypatch):
399
+ import cotop.app
400
+ import cotop.colab
401
+
402
+ home_cache = tmp_path / "home" / ".cache" / "cotop"
403
+ monkeypatch.setattr(cotop.app, "CACHE", home_cache)
404
+ monkeypatch.setattr(cotop.colab, "cli_sign_in", lambda: (_ for _ in ()).throw(AssertionError("signed in")))
405
+ used = []
406
+ monkeypatch.setattr(cotop.app.Dashboard, "run", lambda self: used.append(self))
407
+ cotop.app.run_demo()
408
+ [app] = used
409
+ assert home_cache not in (app.rates.path.parent, app.usage.path.parent)
410
+ assert not (tmp_path / "home").exists()
@@ -0,0 +1,79 @@
1
+ from cotop.colab import still_assigned
2
+ from cotop.model import runtimes_from
3
+ from tests.test_model import G4, LOCAL
4
+
5
+
6
+ def test_a_name_counts_only_while_it_still_means_the_same_vm():
7
+ [r] = runtimes_from([G4], LOCAL, {})
8
+ assert still_assigned(r, [G4], LOCAL)
9
+ assert not still_assigned(r, [], LOCAL) # VM gone: `colab ssh -s` would create a new one
10
+ reused = {"train": {"name": "train", "endpoint": "gpu-g4-new", "running": None}}
11
+ assert not still_assigned(r, [G4], reused) # name now means another VM
12
+ [untracked] = runtimes_from([G4], {}, {})
13
+ assert not still_assigned(untracked, [G4], {})
14
+
15
+
16
+ def test_no_cli_sessions_before_the_cli_has_run(tmp_path, monkeypatch):
17
+ """A first-time user signed in through cotop has no ~/.config/colab-cli yet."""
18
+ import cotop.colab
19
+
20
+ monkeypatch.setattr(cotop.colab, "SESSIONS", tmp_path / "colab-cli" / "sessions.json")
21
+ assert cotop.colab.Colab(None).sessions() == {}
22
+ assert not (tmp_path / "colab-cli").exists() # cotop creates nothing in the CLI's directory
23
+
24
+
25
+ def test_the_proxy_token_never_follows_a_redirect():
26
+ """A runtime's proxy token goes only to the URL Colab returned for that runtime."""
27
+ import threading
28
+ from http.server import BaseHTTPRequestHandler, HTTPServer
29
+
30
+ import pytest
31
+ import requests
32
+
33
+ from cotop.colab import _proxy_get
34
+
35
+ seen = []
36
+
37
+ class Other(BaseHTTPRequestHandler):
38
+ def do_GET(self):
39
+ seen.append(self.headers.get("X-Colab-Runtime-Proxy-Token"))
40
+ self.send_response(200)
41
+ self.end_headers()
42
+ self.wfile.write(b"{}")
43
+
44
+ def log_message(self, *args):
45
+ pass
46
+
47
+ other = HTTPServer(("127.0.0.1", 0), Other)
48
+
49
+ class Proxy(Other):
50
+ def do_GET(self):
51
+ self.send_response(302)
52
+ self.send_header("Location", f"http://localhost:{other.server_port}/elsewhere")
53
+ self.end_headers()
54
+
55
+ proxy = HTTPServer(("127.0.0.1", 0), Proxy)
56
+ for server in (proxy, other):
57
+ threading.Thread(target=server.serve_forever, daemon=True).start()
58
+ try:
59
+ with pytest.raises(requests.HTTPError, match="redirected"):
60
+ _proxy_get(f"http://127.0.0.1:{proxy.server_port}", "TOKEN", "/api/status", 3)
61
+ assert seen == []
62
+ finally:
63
+ proxy.shutdown()
64
+ other.shutdown()
65
+
66
+
67
+ def test_the_cli_library_never_logs_below_warning_or_to_its_log_file(monkeypatch):
68
+ """Its client logs request headers and bodies at DEBUG, even when the root logger takes DEBUG."""
69
+ import logging
70
+
71
+ import cotop.colab # noqa: F401
72
+
73
+ monkeypatch.setattr(logging.getLogger(), "level", logging.DEBUG)
74
+
75
+ for name in ("colab_cli", "colab_cli.client"):
76
+ logger = logging.getLogger(name)
77
+ assert logger.getEffectiveLevel() == logging.WARNING
78
+ handlers = logger.handlers + logging.getLogger().handlers
79
+ assert not [h for h in handlers if str(getattr(h, "baseFilename", "")).endswith("colab.log")]
@@ -0,0 +1,100 @@
1
+ """Only cotop.colab_cli_calls touches google-colab-cli, and it hands over exactly these calls."""
2
+
3
+ import ast
4
+ import importlib.util
5
+ import inspect
6
+ from dataclasses import replace
7
+ from pathlib import Path
8
+
9
+ import pytest
10
+
11
+ import cotop
12
+ from cotop import colab, colab_cli_calls
13
+ from cotop.colab_cli_calls import Google
14
+ from cotop.model import runtimes_from
15
+ from tests.test_model import G4, LOCAL
16
+
17
+ SRC = Path(cotop.__file__).parent
18
+ HANDOFF = colab_cli_calls.__name__
19
+
20
+
21
+ def imported_modules(path: Path) -> list[tuple[str, list[str]]]:
22
+ """(absolute module, names) for each import statement; `from p import x` also yields ("p.x", []).
23
+
24
+ Ordinary import statements only, not importlib or __import__.
25
+ """
26
+ rel = path.relative_to(SRC.parent).with_suffix("")
27
+ package = ".".join(rel.parts if path.name == "__init__.py" else rel.parts[:-1]).removesuffix(".__init__")
28
+ out = []
29
+ for node in ast.walk(ast.parse(path.read_text())):
30
+ if isinstance(node, ast.Import):
31
+ out += [(a.name, []) for a in node.names]
32
+ elif isinstance(node, ast.ImportFrom):
33
+ module = importlib.util.resolve_name("." * node.level + (node.module or ""), package)
34
+ names = [a.name for a in node.names]
35
+ out.append((module, names))
36
+ out += [(f"{module}.{n}", []) for n in names]
37
+ return out
38
+
39
+
40
+ def test_only_the_handoff_module_imports_colab_cli_or_touches_the_session():
41
+ for f in SRC.rglob("*.py"):
42
+ if f == Path(colab_cli_calls.__file__):
43
+ continue
44
+ tree = ast.parse(f.read_text())
45
+ touches = [n for n in ast.walk(tree) if (isinstance(n, ast.Attribute) and n.attr == "_session") or (isinstance(n, ast.Constant) and n.value == "_session")]
46
+ assert not touches, f"{f.name} reaches the session"
47
+ for module, names in imported_modules(f):
48
+ assert module.split(".")[0] != "colab_cli", f"{f.name} imports {module}"
49
+ if module == HANDOFF:
50
+ assert names and set(names) <= set(colab_cli_calls.__all__), f"{f.name} takes {names or 'the module'} from it"
51
+
52
+
53
+ def test_the_handoff_module_exports_exactly_these():
54
+ assert set(colab_cli_calls.__all__) == {"Command", "Google", "colab_argv", "named_sessions", "sign_in"}
55
+ assert {n for n, _ in inspect.getmembers(Google, inspect.isfunction) if not n.startswith("_")} == {"get", "unassign"}
56
+
57
+
58
+ @pytest.fixture
59
+ def ran(monkeypatch):
60
+ """Command lines cotop runs, with the colab path shown as `colab`; the name check passes."""
61
+ lines = []
62
+ done = type("Done", (), {"returncode": 0, "stdout": "", "stderr": ""})()
63
+ monkeypatch.setattr(colab.subprocess, "run", lambda argv, **kw: lines.append(argv) or done)
64
+ monkeypatch.setattr(colab.Colab, "assignments", lambda self: [G4])
65
+ monkeypatch.setattr(colab.Colab, "sessions", lambda self: {"NAME": {"name": "NAME", "endpoint": G4["endpoint"]}})
66
+ return lines
67
+
68
+
69
+ def runtime(name="NAME"):
70
+ [r] = runtimes_from([G4], LOCAL, {})
71
+ return replace(r, name=name)
72
+
73
+
74
+ def test_cotop_runs_exactly_these_command_lines(ran):
75
+ colab.Colab(None).stop(runtime())
76
+ colab.Colab(None).restart_kernel(runtime())
77
+ ran.append(colab.Colab(None).ssh_command(runtime()))
78
+ ran.append(colab.Colab(None, ssh_identity="KEY").ssh_command(runtime()))
79
+ assert [" ".join(["colab", *argv[1:]]) for argv in ran] == [
80
+ "colab stop -s NAME",
81
+ "colab restart-kernel -s NAME",
82
+ "colab ssh -s NAME",
83
+ "colab ssh -s NAME -i KEY",
84
+ ]
85
+
86
+
87
+ @pytest.mark.parametrize("act", ["stop", "restart_kernel", "ssh_command"])
88
+ def test_every_named_action_checks_the_name_still_means_this_runtime(ran, monkeypatch, act):
89
+ """A name stopped and reused since the last poll must not send the action to another VM."""
90
+ monkeypatch.setattr(colab.Colab, "sessions", lambda self: {"NAME": {"name": "NAME", "endpoint": "gpu-reused"}})
91
+ with pytest.raises(colab.RuntimeGone):
92
+ getattr(colab.Colab(None), act)(runtime())
93
+ assert ran == []
94
+
95
+
96
+ def test_colab_argv_refuses_other_commands_and_keys_outside_ssh():
97
+ with pytest.raises(ValueError, match="does not run"):
98
+ colab_cli_calls.colab_argv("new", "NAME")
99
+ with pytest.raises(ValueError, match="takes no SSH key"):
100
+ colab_cli_calls.colab_argv("stop", "NAME", "KEY")
@@ -14,6 +14,7 @@ from cotop.model import (
14
14
  Status,
15
15
  UsageLog,
16
16
  parse_json,
17
+ parse_time,
17
18
  runtimes_from,
18
19
  )
19
20
 
@@ -291,3 +292,23 @@ def test_damaged_cache_files_do_not_stop_cotop(tmp_path):
291
292
  (tmp_path / "r.json").write_text('{"G4/STANDARD": 10.0')
292
293
  assert len(UsageLog(tmp_path / "u.jsonl").samples) == 1
293
294
  assert RateBook(tmp_path / "r.json").rates == {}
295
+
296
+
297
+ def test_history_skips_lines_it_cannot_read(tmp_path):
298
+ """The CLI appends as it goes, so the last line can be half written when cotop reads it."""
299
+ created = '{"timestamp": "2026-11-17T20:59:00+00:00", "event_type": "session_created", "endpoint": "e", "variant": "GPU", "accelerator": "G4", "machine_shape": "STANDARD"}\n'
300
+ (tmp_path / "train.jsonl").write_bytes(
301
+ created.encode()
302
+ + b'[]\n"text"\nnull\n{"event_type": "execution"}\n'
303
+ + b'{"timestamp": "2026-11-17T21:00:00", "event_type": "execution"}\n' # no time zone
304
+ + b'{"timestamp": "2026-11-17T21:01:00+00:00", "event_type": "session_created"}\n' # no endpoint
305
+ + b'{"timestamp": "2026-11-17T21:02:00+00:00", "event_type": 7}\n'
306
+ + b'{"timestamp": 1763413380, "event_type": "execution"}\n'
307
+ + b'{"timestamp": "2026-11-17T21:04:00+00:00", "event_type": "session_created", "endpoint": "f", "machine_shape": "STANDARD"}\n'
308
+ + b'{"timestamp": "2026-11-17T21:05:00+00:00", "event_type": "session_created", "endpoint": "g", "accelerator": "G4"}\n'
309
+ + b'\xff\xfe{"timestamp": "2026-11-17T21:03:00+00:00", "event_ty'
310
+ )
311
+ h = History.load(tmp_path)
312
+ assert [e.summary for e in h.recent("train")] == ["created"]
313
+ assert h.assigned_at() == {"e": parse_time("2026-11-17T20:59:00+00:00")}
314
+ assert [p.endpoint for p in h.past_sessions()] == ["e"]
@@ -278,7 +278,7 @@ wheels = [
278
278
 
279
279
  [[package]]
280
280
  name = "cotop"
281
- version = "0.2.0"
281
+ version = "0.3.0"
282
282
  source = { editable = "." }
283
283
  dependencies = [
284
284
  { name = "google-colab-cli" },
@@ -296,7 +296,7 @@ dev = [
296
296
  requires-dist = [
297
297
  { name = "google-colab-cli", specifier = "~=0.8.0" },
298
298
  { name = "requests" },
299
- { name = "textual", specifier = ">=6" },
299
+ { name = "textual", specifier = ">=6,<9" },
300
300
  ]
301
301
 
302
302
  [package.metadata.requires-dev]
Binary file
Binary file
@@ -1,13 +0,0 @@
1
- from cotop.colab import still_assigned
2
- from cotop.model import runtimes_from
3
- from tests.test_model import G4, LOCAL
4
-
5
-
6
- def test_a_name_counts_only_while_it_still_means_the_same_vm():
7
- [r] = runtimes_from([G4], LOCAL, {})
8
- assert still_assigned(r, [G4], LOCAL)
9
- assert not still_assigned(r, [], LOCAL) # VM gone: `colab ssh -s` would create a new one
10
- reused = {"train": {"name": "train", "endpoint": "gpu-g4-new", "running": None}}
11
- assert not still_assigned(r, [G4], reused) # name now means another VM
12
- [untracked] = runtimes_from([G4], {}, {})
13
- assert not still_assigned(untracked, [G4], {})
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes