cotop 0.1.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 (35) hide show
  1. {cotop-0.1.0 → cotop-0.3.0}/.github/workflows/publish.yml +2 -2
  2. cotop-0.3.0/PKG-INFO +138 -0
  3. cotop-0.3.0/README.md +115 -0
  4. cotop-0.3.0/SECURITY.md +23 -0
  5. {cotop-0.1.0 → cotop-0.3.0}/docs/data-sources.md +32 -9
  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.1.0 → cotop-0.3.0}/pyproject.toml +2 -3
  10. cotop-0.3.0/scripts/demo.tape +36 -0
  11. cotop-0.3.0/scripts/screenshots.py +39 -0
  12. {cotop-0.1.0 → cotop-0.3.0}/src/cotop/app.py +94 -23
  13. {cotop-0.1.0 → cotop-0.3.0}/src/cotop/colab.py +27 -40
  14. cotop-0.3.0/src/cotop/colab_cli_calls.py +70 -0
  15. cotop-0.3.0/src/cotop/demo.py +221 -0
  16. {cotop-0.1.0 → cotop-0.3.0}/src/cotop/model.py +43 -11
  17. cotop-0.3.0/tests/test_app.py +410 -0
  18. cotop-0.3.0/tests/test_colab.py +79 -0
  19. cotop-0.3.0/tests/test_handoff.py +100 -0
  20. {cotop-0.1.0 → cotop-0.3.0}/tests/test_model.py +28 -0
  21. {cotop-0.1.0 → cotop-0.3.0}/uv.lock +2 -4
  22. cotop-0.1.0/PKG-INFO +0 -100
  23. cotop-0.1.0/README.md +0 -76
  24. cotop-0.1.0/docs/images/dashboard.png +0 -0
  25. cotop-0.1.0/docs/images/stop.png +0 -0
  26. cotop-0.1.0/scripts/screenshots.py +0 -205
  27. cotop-0.1.0/tests/test_app.py +0 -231
  28. cotop-0.1.0/tests/test_colab.py +0 -13
  29. {cotop-0.1.0 → cotop-0.3.0}/.gitignore +0 -0
  30. {cotop-0.1.0 → cotop-0.3.0}/LICENSE +0 -0
  31. {cotop-0.1.0 → cotop-0.3.0}/src/cotop/__init__.py +0 -0
  32. {cotop-0.1.0 → cotop-0.3.0}/src/cotop/widgets.py +0 -0
  33. {cotop-0.1.0 → cotop-0.3.0}/tests/__init__.py +0 -0
  34. {cotop-0.1.0 → cotop-0.3.0}/tests/fixtures/resources_g4.txt +0 -0
  35. {cotop-0.1.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
cotop-0.3.0/PKG-INFO ADDED
@@ -0,0 +1,138 @@
1
+ Metadata-Version: 2.5
2
+ Name: cotop
3
+ Version: 0.3.0
4
+ Summary: A top-like terminal dashboard for Google Colab runtimes and compute units
5
+ Project-URL: Homepage, https://github.com/benngarcia/cotop
6
+ Project-URL: Issues, https://github.com/benngarcia/cotop/issues
7
+ License-Expression: Apache-2.0
8
+ License-File: LICENSE
9
+ Keywords: colab,dashboard,google-colab,gpu,textual,tui
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Operating System :: MacOS
15
+ Classifier: Operating System :: POSIX :: Linux
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Topic :: System :: Monitoring
18
+ Requires-Python: >=3.12
19
+ Requires-Dist: google-colab-cli~=0.8.0
20
+ Requires-Dist: requests
21
+ Requires-Dist: textual<9,>=6
22
+ Description-Content-Type: text/markdown
23
+
24
+ # cotop
25
+
26
+ `top` for Google Colab: compute units, runtimes and what they cost, live in your terminal.
27
+
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
+
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
+ - **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.
32
+ - **The selected runtime:** a braille graph of GPU utilization, read every two seconds, with VRAM, RAM and disk meters, what it has cost and its recent activity. On a runtime without a GPU, the graph shows RAM.
33
+ - **History:** press `h` for past sessions, how long each ran and roughly what it cost.
34
+ - **Actions:** stop a runtime, restart its kernel, or open a shell on it.
35
+
36
+ cotop works on top of the official [Colab CLI](https://pypi.org/project/google-colab-cli/). It uses the CLI's sign-in, session names and history, so runtimes you start with `colab new` show up by name.
37
+
38
+ ## Install
39
+
40
+ ```sh
41
+ uv tool install cotop
42
+ cotop
43
+ cotop --demo # a made-up account with twelve runtimes; no sign-in
44
+ ```
45
+
46
+ cotop needs Python 3.12 or later. It is tested on macOS and should work on Linux. If you have not signed in to the Colab CLI yet, cotop runs the same Google sign-in on first launch. On macOS, Keychain may ask once whether cotop's Python can read the Colab CLI's token.
47
+
48
+ ## Keys
49
+
50
+ | Key | Action |
51
+ |---|---|
52
+ | `↑` `↓` or `k` `j` | Select a runtime |
53
+ | `h` | Past sessions and the hardware your account can use |
54
+ | `r` | Refresh now (cotop also refreshes every 15 seconds) |
55
+ | `s` | Stop the selected runtime |
56
+ | `R` | Restart its kernel |
57
+ | `x` | Open a shell on it with `colab ssh` |
58
+ | `?` | Show every key |
59
+ | `q` | Quit |
60
+
61
+ ![The stop confirmation, with Cancel selected](docs/images/stop.png)
62
+
63
+ Stop and restart ask first, and Cancel has focus. `colab ssh` looks for `~/.ssh/id_ed25519.pub` or `~/.ssh/id_ecdsa.pub`. For another key, start cotop with `cotop -i ~/.ssh/KEY.pub`. Restart and ssh work only on runtimes started with the Colab CLI. Stop works on any runtime.
64
+
65
+ ## Which numbers are estimates
66
+
67
+ Colab reports one hourly rate for the whole account, not one per runtime. cotop shows a per-runtime rate as follows:
68
+
69
+ - With one runtime, the rate is exact.
70
+ - With several runtimes on the same hardware, cotop splits the total evenly.
71
+ - Otherwise cotop uses a rate it learned earlier, when only that hardware was running. These rates are stored in `~/.cache/cotop/rates.json`.
72
+ - With no learned rate, the column shows `?`.
73
+
74
+ Estimates start with `≈`, and upper bounds start with `≤`. Colab boots VMs before it assigns them, so uptime and spend count from the assignment time in the CLI's history. A runtime opened in a browser has no assignment time, so cotop counts from VM boot and shows an upper bound.
75
+
76
+ [docs/data-sources.md](docs/data-sources.md) lists each request cotop makes and what it reads.
77
+
78
+ ## What cotop can touch
79
+
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.
121
+
122
+ ## Not affiliated with Google
123
+
124
+ cotop is an independent project. It relies on internal parts of `google-colab-cli` and on Colab endpoints that are not public APIs. Either can change without notice. cotop pins the Colab CLI's minor version for that reason.
125
+
126
+ ## Development
127
+
128
+ ```sh
129
+ uv sync
130
+ uv run pytest
131
+ uv run python scripts/screenshots.py OUT_DIR # README screenshots, rendered from the demo account
132
+ ```
133
+
134
+ To release, set `version` in `pyproject.toml`, then push a matching tag such as `v0.1.0`. The [publish workflow](.github/workflows/publish.yml) builds the package and uploads it to PyPI with trusted publishing.
135
+
136
+ ## License
137
+
138
+ [Apache 2.0](LICENSE)
cotop-0.3.0/README.md ADDED
@@ -0,0 +1,115 @@
1
+ # cotop
2
+
3
+ `top` for Google Colab: compute units, runtimes and what they cost, live in your terminal.
4
+
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
+
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
+ - **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.
9
+ - **The selected runtime:** a braille graph of GPU utilization, read every two seconds, with VRAM, RAM and disk meters, what it has cost and its recent activity. On a runtime without a GPU, the graph shows RAM.
10
+ - **History:** press `h` for past sessions, how long each ran and roughly what it cost.
11
+ - **Actions:** stop a runtime, restart its kernel, or open a shell on it.
12
+
13
+ cotop works on top of the official [Colab CLI](https://pypi.org/project/google-colab-cli/). It uses the CLI's sign-in, session names and history, so runtimes you start with `colab new` show up by name.
14
+
15
+ ## Install
16
+
17
+ ```sh
18
+ uv tool install cotop
19
+ cotop
20
+ cotop --demo # a made-up account with twelve runtimes; no sign-in
21
+ ```
22
+
23
+ cotop needs Python 3.12 or later. It is tested on macOS and should work on Linux. If you have not signed in to the Colab CLI yet, cotop runs the same Google sign-in on first launch. On macOS, Keychain may ask once whether cotop's Python can read the Colab CLI's token.
24
+
25
+ ## Keys
26
+
27
+ | Key | Action |
28
+ |---|---|
29
+ | `↑` `↓` or `k` `j` | Select a runtime |
30
+ | `h` | Past sessions and the hardware your account can use |
31
+ | `r` | Refresh now (cotop also refreshes every 15 seconds) |
32
+ | `s` | Stop the selected runtime |
33
+ | `R` | Restart its kernel |
34
+ | `x` | Open a shell on it with `colab ssh` |
35
+ | `?` | Show every key |
36
+ | `q` | Quit |
37
+
38
+ ![The stop confirmation, with Cancel selected](docs/images/stop.png)
39
+
40
+ Stop and restart ask first, and Cancel has focus. `colab ssh` looks for `~/.ssh/id_ed25519.pub` or `~/.ssh/id_ecdsa.pub`. For another key, start cotop with `cotop -i ~/.ssh/KEY.pub`. Restart and ssh work only on runtimes started with the Colab CLI. Stop works on any runtime.
41
+
42
+ ## Which numbers are estimates
43
+
44
+ Colab reports one hourly rate for the whole account, not one per runtime. cotop shows a per-runtime rate as follows:
45
+
46
+ - With one runtime, the rate is exact.
47
+ - With several runtimes on the same hardware, cotop splits the total evenly.
48
+ - Otherwise cotop uses a rate it learned earlier, when only that hardware was running. These rates are stored in `~/.cache/cotop/rates.json`.
49
+ - With no learned rate, the column shows `?`.
50
+
51
+ Estimates start with `≈`, and upper bounds start with `≤`. Colab boots VMs before it assigns them, so uptime and spend count from the assignment time in the CLI's history. A runtime opened in a browser has no assignment time, so cotop counts from VM boot and shows an upper bound.
52
+
53
+ [docs/data-sources.md](docs/data-sources.md) lists each request cotop makes and what it reads.
54
+
55
+ ## What cotop can touch
56
+
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.
98
+
99
+ ## Not affiliated with Google
100
+
101
+ cotop is an independent project. It relies on internal parts of `google-colab-cli` and on Colab endpoints that are not public APIs. Either can change without notice. cotop pins the Colab CLI's minor version for that reason.
102
+
103
+ ## Development
104
+
105
+ ```sh
106
+ uv sync
107
+ uv run pytest
108
+ uv run python scripts/screenshots.py OUT_DIR # README screenshots, rendered from the demo account
109
+ ```
110
+
111
+ To release, set `version` in `pyproject.toml`, then push a matching tag such as `v0.1.0`. The [publish workflow](.github/workflows/publish.yml) builds the package and uploads it to PyPI with trusted publishing.
112
+
113
+ ## License
114
+
115
+ [Apache 2.0](LICENSE)
@@ -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,18 +1,26 @@
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. Every
5
- request is a GET.
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.
11
+
12
+ `cotop --demo` runs on `src/cotop/demo.py`, a made-up account, and sends no
13
+ requests at all.
6
14
 
7
15
  | Panel | Source | Notes |
8
16
  |---|---|---|
9
17
  | Account email | `openidconnect.googleapis.com/v1/userinfo` | Signed in with the Colab CLI's OAuth token from the OS keyring |
10
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 |
11
19
  | Runtimes | `/tun/m/assignments` | Every VM the account holds, including ones opened in a browser. These show as *untracked* |
12
- | 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 |
13
21
  | Kernel state, idle time, clients | Runtime proxy `/api/kernels`, `/api/status` | Requests carry `?no_track_activity=1` |
14
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 |
15
- | 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 |
16
24
 
17
25
  ## Estimates
18
26
 
@@ -37,19 +45,34 @@ the fall in balance between the first and last settled step in the past hour,
37
45
  logged in `~/.cache/cotop/usage.jsonl`. You can compare it with the rate
38
46
  Colab reports.
39
47
 
48
+ ## Watching did not keep an idle runtime alive
49
+
50
+ Tested on 2026-11-17 with two idle CPU runtimes started with `colab new`, neither
51
+ with a kernel. One was read the way cotop reads a runtime: the same endpoints
52
+ and flag, its resources about every 2 seconds and its kernels about every 16 to
53
+ 20 seconds. The other was never touched. Colab reclaimed both in the same
54
+ one-minute check, 3 hours 1 minute after they started.
55
+
56
+ The read requests carry `no_track_activity=1`, and Jupyter honors it: the
57
+ runtime's `last_activity` did not move after flagged reads, and did move after
58
+ the same reads without the flag. Colab does not document what it counts as
59
+ idle activity.
60
+
40
61
  ## Not verified
41
62
 
42
- - Whether reading a runtime's Jupyter API delays Colab's idle shutdown. Requests
43
- send `no_track_activity=1`, including the reads every 2 seconds. Colab's own
44
- idle signal is not documented.
45
63
  - That billing starts at assignment rather than at VM boot.
64
+ - Whether Colab reclaimed these runtimes for being idle or at a fixed time
65
+ limit near 3 hours. The test had no runtime that stayed active, so it cannot
66
+ tell the two apart.
67
+ - Runtimes with an idle kernel, and GPU or TPU runtimes. The test covered CPU
68
+ runtimes without a kernel only.
46
69
 
47
70
  ## Actions
48
71
 
49
72
  | Key | Runs | Notes |
50
73
  |---|---|---|
51
74
  | `s` | `colab stop -s NAME` | For an untracked runtime, the CLI's `Client.unassign(endpoint)`, because no name exists |
52
- | `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 |
53
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 |
54
77
 
55
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.1.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"
@@ -20,9 +20,8 @@ classifiers = [
20
20
  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
- "packaging",
24
23
  "requests",
25
- "textual>=6",
24
+ "textual>=6,<9", # 6.0 and 8.2 tested; 9 may change the DataTable and screen APIs cotop uses
26
25
  ]
27
26
 
28
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"
@@ -0,0 +1,39 @@
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`.
3
+
4
+ uv run python scripts/screenshots.py OUT_DIR
5
+
6
+ writes OUT_DIR/dashboard.svg (138x40), small.svg (80x24), large.svg (180x52) and
7
+ stop.svg. To get the PNGs in docs/images:
8
+
9
+ chrome --headless --force-device-scale-factor=2 --window-size=1380,880 \\
10
+ --screenshot=docs/images/dashboard.png OUT_DIR/dashboard.svg
11
+ """
12
+
13
+ import asyncio
14
+ import sys
15
+ import tempfile
16
+ from pathlib import Path
17
+
18
+ from cotop.app import demo_dashboard
19
+
20
+ SIZES = {"dashboard": (138, 40), "small": (80, 24), "large": (180, 52)}
21
+
22
+
23
+ async def shoot(out: Path) -> None:
24
+ for name, size in SIZES.items():
25
+ with tempfile.TemporaryDirectory() as cache:
26
+ app = demo_dashboard(Path(cache))
27
+ async with app.run_test(size=size) as pilot:
28
+ for _ in range(3):
29
+ await app.workers.wait_for_complete()
30
+ await pilot.pause()
31
+ app.save_screenshot(f"{name}.svg", path=str(out))
32
+ if name == "dashboard":
33
+ await pilot.press("down", "down", "down", "down", "down", "s")
34
+ await pilot.pause()
35
+ app.save_screenshot("stop.svg", path=str(out))
36
+
37
+
38
+ if __name__ == "__main__":
39
+ asyncio.run(shoot(Path(sys.argv[1])))