pbs-tui 0.1.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 (10) hide show
  1. pbs_tui-0.1.0/PKG-INFO +143 -0
  2. pbs_tui-0.1.0/README.md +133 -0
  3. pbs_tui-0.1.0/pyproject.toml +25 -0
  4. pbs_tui-0.1.0/src/pbs_tui/__init__.py +16 -0
  5. pbs_tui-0.1.0/src/pbs_tui/__main__.py +4 -0
  6. pbs_tui-0.1.0/src/pbs_tui/app.py +638 -0
  7. pbs_tui-0.1.0/src/pbs_tui/app.tcss +50 -0
  8. pbs_tui-0.1.0/src/pbs_tui/data.py +91 -0
  9. pbs_tui-0.1.0/src/pbs_tui/fetcher.py +776 -0
  10. pbs_tui-0.1.0/src/pbs_tui/samples.py +128 -0
pbs_tui-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,143 @@
1
+ Metadata-Version: 2.3
2
+ Name: pbs-tui
3
+ Version: 0.1.0
4
+ Summary: Textual TUI dashboard for monitoring PBS Pro schedulers
5
+ Author: Sam Foreman, Argonne Leadership Computing Facility
6
+ Author-email: Sam Foreman <foremans@anl.gov>
7
+ Requires-Dist: textual
8
+ Requires-Python: >=3.10
9
+ Description-Content-Type: text/markdown
10
+
11
+ # PBS Pro Textual TUI
12
+
13
+
14
+ <center>
15
+ <img width="48%" alt="ScreenShot-2025-09-16-172415@2x" src="https://github.com/user-attachments/assets/0947b9f3-3b55-42b9-8a6d-8e301492b7f7" /> <img width="48%" alt="ScreenShot-2025-09-16-172702@2x" src="https://github.com/user-attachments/assets/c3a5a8c4-3e28-4ec3-b4e4-91438f745ced" />
16
+ </center>
17
+
18
+
19
+ A terminal user interface built with [Textual](https://textual.textualize.io/) for monitoring
20
+ [PBS Pro](https://altair.com/pbs-professional) schedulers at the
21
+ [Argonne Leadership Computing Facility](https://alcf.anl.gov). The dashboard surfaces job,
22
+ queue, and node activity in a single view and refreshes itself automatically so operators can
23
+ track workload health in real time.
24
+
25
+ ## Features
26
+
27
+ - **Live PBS data** – prefers the JSON (`-F json`) output of `qstat`/`pbsnodes` and falls back to
28
+ XML or text parsing so schedulers without newer flags continue to work.
29
+ - **Automatic refresh** – updates every 30 seconds by default with a manual refresh binding
30
+ (`r`).
31
+ - **Summary cards** – quick totals for job states, node states, and queue health.
32
+ - **Rich tables** – sortable (via cursor) tables for jobs, nodes, and queues with detail views
33
+ for the selected record.
34
+ - **Fallback sample data** – optional bundled data makes it easy to demo the interface without
35
+ connecting to a production scheduler (`PBS_TUI_SAMPLE_DATA=1`).
36
+ - **Inline snapshot** – render the current queue as a Rich table with `pbs-tui --inline` and
37
+ optionally write a Markdown summary alongside it.
38
+
39
+ ## Installation
40
+
41
+ 1. Ensure Python 3.10 or newer is available.
42
+ 2. Install the project (and Textual) in your environment:
43
+
44
+ ```bash
45
+ pip install -e .
46
+ ```
47
+
48
+ Development extras (formatting, etc.) can be installed with `pip install -e .[dev]`.
49
+
50
+ ## Usage
51
+
52
+ Launch the dashboard once the PBS CLI utilities (`qstat`, `pbsnodes`) are on the `PATH`:
53
+
54
+ ```bash
55
+ pbs-tui
56
+ ```
57
+
58
+ The same entry point is available via `python -m pbs_tui`. The interface displays a summary
59
+ panel, tables for jobs/nodes/queues, and a detail pane for the selected row. Refreshing happens
60
+ automatically; press `r` to force an immediate update.
61
+
62
+ Adjust the refresh cadence with `pbs-tui --refresh-interval 60` (seconds) if you prefer a slower or
63
+ faster polling loop.
64
+
65
+ ### Key bindings
66
+
67
+ | Key | Action |
68
+ |:---:|:---------------------- |
69
+ | `q` | Quit the application |
70
+ | `r` | Refresh immediately |
71
+ | `j` | Focus the jobs table |
72
+ | `n` | Focus the nodes table |
73
+ | `u` | Focus the queues table |
74
+
75
+ Use the arrow keys/`PageUp`/`PageDown` to move through rows once a table has focus.
76
+
77
+ ### Sample mode
78
+
79
+ If you want to explore the UI without a live PBS cluster, export `PBS_TUI_SAMPLE_DATA=1`
80
+ (or pass `force_sample=True` to `PBSDataFetcher`). The application will display bundled example
81
+ jobs, nodes, and queues along with a warning banner indicating that the data is synthetic.
82
+
83
+ ### Headless / automated runs
84
+
85
+ For automated testing or CI environments without an interactive terminal you can run the TUI in
86
+ headless mode by exporting `PBS_TUI_HEADLESS=1`. Pairing this with `PBS_TUI_AUTOPILOT=quit`
87
+ presses the `q` binding automatically after startup so `pbs-tui` exits cleanly once the interface
88
+ has rendered its first update.
89
+
90
+ ### Inline snapshot mode
91
+
92
+ When running non-interactively you can emit a Rich-rendered table summarising the active PBS jobs
93
+ instead of starting the Textual interface:
94
+
95
+ ```bash
96
+ PBS_TUI_SAMPLE_DATA=1 pbs-tui --inline
97
+ ```
98
+
99
+ The command prints a table that can be pasted into terminals that support Unicode box drawing. Pass
100
+ `--file snapshot.md` alongside `--inline` to also write an aligned Markdown table to `snapshot.md`
101
+ for sharing in chat or documentation systems. Any warnings raised while collecting data are written
102
+ to standard error so they remain visible in logs.
103
+
104
+ ## Architecture
105
+
106
+ - `pbs_tui.fetcher.PBSDataFetcher` orchestrates `qstat`/`pbsnodes` calls, preferring JSON output and
107
+ falling back to XML/text before converting everything into structured dataclasses (`Job`, `Node`,
108
+ `Queue`).
109
+ - `pbs_tui.app.PBSTUI` is the Textual application that renders the dashboard, periodically asks
110
+ the fetcher for new data, and updates the widgets.
111
+ - `pbs_tui.samples.sample_snapshot` provides the demonstration snapshot used when PBS commands
112
+ cannot be executed.
113
+
114
+ The UI styles are defined in `pbs_tui/app.tcss`. Adjust the CSS to change layout or theme
115
+ attributes.
116
+
117
+ ## Development notes
118
+
119
+ - The application refresh interval defaults to 30 seconds. Pass a different value to
120
+ `PBSTUI(refresh_interval=...)` if desired.
121
+ - Errors encountered while running PBS commands are surfaced in the status bar so operators can
122
+ quickly see when data is stale.
123
+ - When both PBS utilities are unavailable and the fallback is disabled, the UI will show an empty
124
+ dashboard with an error message in the status bar.
125
+
126
+ ## Screenshots
127
+
128
+ - `pbs-tui`:
129
+
130
+ <img width="2498" height="1828" alt="ScreenShot-2025-09-16-172415@2x" src="https://github.com/user-attachments/assets/419cecb6-25a1-4007-8456-38bd80fb4ae7" />
131
+
132
+
133
+ - Keys and Help Panel:
134
+
135
+ <img width="2498" height="1828" alt="ScreenShot-2025-09-16-172451@2x" src="https://github.com/user-attachments/assets/d521d137-1135-4503-bcc0-2b9dba35d252" />
136
+
137
+ - Command palette:
138
+
139
+ <img width="2498" height="1828" alt="ScreenShot-2025-09-16-172546@2x" src="https://github.com/user-attachments/assets/5804c99a-621a-4cce-adde-092f6d324824" />
140
+
141
+ - theme support:
142
+
143
+ <img width="2498" height="1828" alt="ScreenShot-2025-09-16-172702@2x" src="https://github.com/user-attachments/assets/d4009439-2ea7-49f5-9c75-5d25f7b13771" />
pbs_tui-0.1.0/README.md ADDED
@@ -0,0 +1,133 @@
1
+ # PBS Pro Textual TUI
2
+
3
+
4
+ <center>
5
+ <img width="48%" alt="ScreenShot-2025-09-16-172415@2x" src="https://github.com/user-attachments/assets/0947b9f3-3b55-42b9-8a6d-8e301492b7f7" /> <img width="48%" alt="ScreenShot-2025-09-16-172702@2x" src="https://github.com/user-attachments/assets/c3a5a8c4-3e28-4ec3-b4e4-91438f745ced" />
6
+ </center>
7
+
8
+
9
+ A terminal user interface built with [Textual](https://textual.textualize.io/) for monitoring
10
+ [PBS Pro](https://altair.com/pbs-professional) schedulers at the
11
+ [Argonne Leadership Computing Facility](https://alcf.anl.gov). The dashboard surfaces job,
12
+ queue, and node activity in a single view and refreshes itself automatically so operators can
13
+ track workload health in real time.
14
+
15
+ ## Features
16
+
17
+ - **Live PBS data** – prefers the JSON (`-F json`) output of `qstat`/`pbsnodes` and falls back to
18
+ XML or text parsing so schedulers without newer flags continue to work.
19
+ - **Automatic refresh** – updates every 30 seconds by default with a manual refresh binding
20
+ (`r`).
21
+ - **Summary cards** – quick totals for job states, node states, and queue health.
22
+ - **Rich tables** – sortable (via cursor) tables for jobs, nodes, and queues with detail views
23
+ for the selected record.
24
+ - **Fallback sample data** – optional bundled data makes it easy to demo the interface without
25
+ connecting to a production scheduler (`PBS_TUI_SAMPLE_DATA=1`).
26
+ - **Inline snapshot** – render the current queue as a Rich table with `pbs-tui --inline` and
27
+ optionally write a Markdown summary alongside it.
28
+
29
+ ## Installation
30
+
31
+ 1. Ensure Python 3.10 or newer is available.
32
+ 2. Install the project (and Textual) in your environment:
33
+
34
+ ```bash
35
+ pip install -e .
36
+ ```
37
+
38
+ Development extras (formatting, etc.) can be installed with `pip install -e .[dev]`.
39
+
40
+ ## Usage
41
+
42
+ Launch the dashboard once the PBS CLI utilities (`qstat`, `pbsnodes`) are on the `PATH`:
43
+
44
+ ```bash
45
+ pbs-tui
46
+ ```
47
+
48
+ The same entry point is available via `python -m pbs_tui`. The interface displays a summary
49
+ panel, tables for jobs/nodes/queues, and a detail pane for the selected row. Refreshing happens
50
+ automatically; press `r` to force an immediate update.
51
+
52
+ Adjust the refresh cadence with `pbs-tui --refresh-interval 60` (seconds) if you prefer a slower or
53
+ faster polling loop.
54
+
55
+ ### Key bindings
56
+
57
+ | Key | Action |
58
+ |:---:|:---------------------- |
59
+ | `q` | Quit the application |
60
+ | `r` | Refresh immediately |
61
+ | `j` | Focus the jobs table |
62
+ | `n` | Focus the nodes table |
63
+ | `u` | Focus the queues table |
64
+
65
+ Use the arrow keys/`PageUp`/`PageDown` to move through rows once a table has focus.
66
+
67
+ ### Sample mode
68
+
69
+ If you want to explore the UI without a live PBS cluster, export `PBS_TUI_SAMPLE_DATA=1`
70
+ (or pass `force_sample=True` to `PBSDataFetcher`). The application will display bundled example
71
+ jobs, nodes, and queues along with a warning banner indicating that the data is synthetic.
72
+
73
+ ### Headless / automated runs
74
+
75
+ For automated testing or CI environments without an interactive terminal you can run the TUI in
76
+ headless mode by exporting `PBS_TUI_HEADLESS=1`. Pairing this with `PBS_TUI_AUTOPILOT=quit`
77
+ presses the `q` binding automatically after startup so `pbs-tui` exits cleanly once the interface
78
+ has rendered its first update.
79
+
80
+ ### Inline snapshot mode
81
+
82
+ When running non-interactively you can emit a Rich-rendered table summarising the active PBS jobs
83
+ instead of starting the Textual interface:
84
+
85
+ ```bash
86
+ PBS_TUI_SAMPLE_DATA=1 pbs-tui --inline
87
+ ```
88
+
89
+ The command prints a table that can be pasted into terminals that support Unicode box drawing. Pass
90
+ `--file snapshot.md` alongside `--inline` to also write an aligned Markdown table to `snapshot.md`
91
+ for sharing in chat or documentation systems. Any warnings raised while collecting data are written
92
+ to standard error so they remain visible in logs.
93
+
94
+ ## Architecture
95
+
96
+ - `pbs_tui.fetcher.PBSDataFetcher` orchestrates `qstat`/`pbsnodes` calls, preferring JSON output and
97
+ falling back to XML/text before converting everything into structured dataclasses (`Job`, `Node`,
98
+ `Queue`).
99
+ - `pbs_tui.app.PBSTUI` is the Textual application that renders the dashboard, periodically asks
100
+ the fetcher for new data, and updates the widgets.
101
+ - `pbs_tui.samples.sample_snapshot` provides the demonstration snapshot used when PBS commands
102
+ cannot be executed.
103
+
104
+ The UI styles are defined in `pbs_tui/app.tcss`. Adjust the CSS to change layout or theme
105
+ attributes.
106
+
107
+ ## Development notes
108
+
109
+ - The application refresh interval defaults to 30 seconds. Pass a different value to
110
+ `PBSTUI(refresh_interval=...)` if desired.
111
+ - Errors encountered while running PBS commands are surfaced in the status bar so operators can
112
+ quickly see when data is stale.
113
+ - When both PBS utilities are unavailable and the fallback is disabled, the UI will show an empty
114
+ dashboard with an error message in the status bar.
115
+
116
+ ## Screenshots
117
+
118
+ - `pbs-tui`:
119
+
120
+ <img width="2498" height="1828" alt="ScreenShot-2025-09-16-172415@2x" src="https://github.com/user-attachments/assets/419cecb6-25a1-4007-8456-38bd80fb4ae7" />
121
+
122
+
123
+ - Keys and Help Panel:
124
+
125
+ <img width="2498" height="1828" alt="ScreenShot-2025-09-16-172451@2x" src="https://github.com/user-attachments/assets/d521d137-1135-4503-bcc0-2b9dba35d252" />
126
+
127
+ - Command palette:
128
+
129
+ <img width="2498" height="1828" alt="ScreenShot-2025-09-16-172546@2x" src="https://github.com/user-attachments/assets/5804c99a-621a-4cce-adde-092f6d324824" />
130
+
131
+ - theme support:
132
+
133
+ <img width="2498" height="1828" alt="ScreenShot-2025-09-16-172702@2x" src="https://github.com/user-attachments/assets/d4009439-2ea7-49f5-9c75-5d25f7b13771" />
pbs_tui-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,25 @@
1
+ [build-system]
2
+ requires = ["uv_build>=0.8.17,<0.9.0"]
3
+ build-backend = "uv_build"
4
+
5
+ [project]
6
+ name = "pbs-tui"
7
+ version = "0.1.0"
8
+ # dynamic = ["version"]
9
+ description = "Textual TUI dashboard for monitoring PBS Pro schedulers"
10
+ readme = "README.md"
11
+ authors = [
12
+ {name = "Sam Foreman", email = "foremans@anl.gov" },
13
+ {name = "Argonne Leadership Computing Facility"}
14
+ ]
15
+ requires-python = ">=3.10"
16
+ dependencies = [
17
+ "textual",
18
+ ]
19
+
20
+ [project.scripts]
21
+ pbs-tui = "pbs_tui.app:run"
22
+
23
+ [tool.setuptools.packages.find]
24
+ where = ["."]
25
+ include = ["pbs_tui", "pbs_tui/app.tcss"]
pbs_tui-0.1.0/src/pbs_tui/__init__.py ADDED
@@ -0,0 +1,16 @@
1
+ """PBS Pro Textual TUI."""
2
+
3
+ from .app import PBSTUI, run, snapshot_to_markdown
4
+ from .data import Job, Node, Queue, SchedulerSnapshot
5
+
6
+ __all__ = [
7
+ "PBSTUI",
8
+ "Job",
9
+ "Node",
10
+ "Queue",
11
+ "SchedulerSnapshot",
12
+ "run",
13
+ "snapshot_to_markdown",
14
+ ]
15
+
16
+ __version__ = "0.1.0"
pbs_tui-0.1.0/src/pbs_tui/__main__.py ADDED
@@ -0,0 +1,4 @@
1
+ from .app import run
2
+
3
+ if __name__ == "__main__":
4
+ run()