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.
- {cotop-0.2.0 → cotop-0.3.0}/.github/workflows/publish.yml +2 -2
- {cotop-0.2.0 → cotop-0.3.0}/PKG-INFO +48 -10
- {cotop-0.2.0 → cotop-0.3.0}/README.md +46 -8
- cotop-0.3.0/SECURITY.md +23 -0
- {cotop-0.2.0 → cotop-0.3.0}/docs/data-sources.md +11 -7
- cotop-0.3.0/docs/images/dashboard.png +0 -0
- cotop-0.3.0/docs/images/demo.gif +0 -0
- cotop-0.3.0/docs/images/stop.png +0 -0
- {cotop-0.2.0 → cotop-0.3.0}/pyproject.toml +2 -2
- cotop-0.3.0/scripts/demo.tape +36 -0
- {cotop-0.2.0 → cotop-0.3.0}/scripts/screenshots.py +2 -1
- {cotop-0.2.0 → cotop-0.3.0}/src/cotop/app.py +22 -3
- {cotop-0.2.0 → cotop-0.3.0}/src/cotop/colab.py +20 -35
- cotop-0.3.0/src/cotop/colab_cli_calls.py +70 -0
- {cotop-0.2.0 → cotop-0.3.0}/src/cotop/model.py +16 -4
- {cotop-0.2.0 → cotop-0.3.0}/tests/test_app.py +120 -2
- cotop-0.3.0/tests/test_colab.py +79 -0
- cotop-0.3.0/tests/test_handoff.py +100 -0
- {cotop-0.2.0 → cotop-0.3.0}/tests/test_model.py +21 -0
- {cotop-0.2.0 → cotop-0.3.0}/uv.lock +2 -2
- cotop-0.2.0/docs/images/dashboard.png +0 -0
- cotop-0.2.0/docs/images/stop.png +0 -0
- cotop-0.2.0/tests/test_colab.py +0 -13
- {cotop-0.2.0 → cotop-0.3.0}/.gitignore +0 -0
- {cotop-0.2.0 → cotop-0.3.0}/LICENSE +0 -0
- {cotop-0.2.0 → cotop-0.3.0}/src/cotop/__init__.py +0 -0
- {cotop-0.2.0 → cotop-0.3.0}/src/cotop/demo.py +0 -0
- {cotop-0.2.0 → cotop-0.3.0}/src/cotop/widgets.py +0 -0
- {cotop-0.2.0 → cotop-0.3.0}/tests/__init__.py +0 -0
- {cotop-0.2.0 → cotop-0.3.0}/tests/fixtures/resources_g4.txt +0 -0
- {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.
|
|
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
|
|
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
|
-

|
|
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
|
-
| `
|
|
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
|

|
|
@@ -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
|
-
##
|
|
78
|
+
## What cotop can touch
|
|
78
79
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
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
|
-

|
|
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
|
-
| `
|
|
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
|

|
|
@@ -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
|
-
##
|
|
55
|
+
## What cotop can touch
|
|
55
56
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
|
cotop-0.3.0/SECURITY.md
ADDED
|
@@ -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
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
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`.
|
|
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` |
|
|
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
|
-
| `
|
|
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.
|
|
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
|
-
("
|
|
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
|
-
|
|
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,
|
|
38
|
-
self.
|
|
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(
|
|
41
|
+
return cls(cli_sign_in(), ssh_identity)
|
|
45
42
|
|
|
46
43
|
def _get(self, url: str, **params):
|
|
47
|
-
|
|
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
|
-
|
|
57
|
+
self.google.unassign(runtime.endpoint)
|
|
63
58
|
return f"Stopped {runtime.endpoint}."
|
|
64
59
|
self.confirm_still_assigned(runtime)
|
|
65
|
-
return _cli("stop",
|
|
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",
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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(
|
|
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 {
|
|
133
|
-
return lines[-1] if lines else f"colab {
|
|
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
|
-
|
|
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
|
-
|
|
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("
|
|
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", "
|
|
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.
|
|
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
|
cotop-0.2.0/docs/images/stop.png
DELETED
|
Binary file
|
cotop-0.2.0/tests/test_colab.py
DELETED
|
@@ -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
|
|
File without changes
|