host-pressure 0.1.1__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.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 El Fenomeno
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,203 @@
1
+ Metadata-Version: 2.4
2
+ Name: host-pressure
3
+ Version: 0.1.1
4
+ Classifier: Development Status :: 4 - Beta
5
+ Classifier: Environment :: Console
6
+ Classifier: Intended Audience :: Developers
7
+ Classifier: Intended Audience :: System Administrators
8
+ Classifier: Operating System :: MacOS
9
+ Classifier: Operating System :: Microsoft :: Windows
10
+ Classifier: Operating System :: POSIX :: Linux
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3 :: Only
13
+ Classifier: Topic :: System :: Monitoring
14
+ Classifier: Topic :: System :: Systems Administration
15
+ License-File: LICENSE
16
+ Summary: A command-line resource check that tells you whether your machine has room for another job.
17
+ Keywords: cpu,memory,swap,pressure,psi,load,monitoring,health-check,cli,macos,linux,windows
18
+ Author: El Fenomeno
19
+ License-Expression: MIT
20
+ Requires-Python: >=3.9
21
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
22
+ Project-URL: Homepage, https://github.com/elfenomenokim/host-pressure
23
+ Project-URL: Issues, https://github.com/elfenomenokim/host-pressure/issues
24
+ Project-URL: Repository, https://github.com/elfenomenokim/host-pressure
25
+
26
+ # host-pressure
27
+ [한국어](README.ko.md)
28
+
29
+ A command-line resource check that tells you whether your machine has room for another job.
30
+
31
+ <picture>
32
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/demo/dark.gif">
33
+ <img src="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/demo/light.gif" alt="A resource line, an ok verdict, and repeated readings from the labeled demo fixture" width="1200">
34
+ </picture>
35
+
36
+ The recording runs the Python CLI with [synthetic readings](docs/demo/fixture.py). It shows formatting and verdicts, not a measurement of a real host.
37
+
38
+ ## Install
39
+
40
+ ```sh
41
+ pipx install host-pressure
42
+ uv tool install host-pressure
43
+ pip install host-pressure
44
+ ```
45
+
46
+ Python 3.9+. Wheels install the Rust command and the importable Python package. A source install needs Rust.
47
+
48
+ | Platform | Observed runs |
49
+ |---|---|
50
+ | macOS arm64 | Rust command and Python library |
51
+ | Linux arm64 | Rust command and Python library on Ubuntu 24.04 |
52
+ | Windows x64 | Both commands on Windows 11 |
53
+
54
+ ## Quick start
55
+
56
+ You can read one line, check whether to start work, or choose fields for a status bar. These outputs were captured from the demo fixture; your readings will differ.
57
+
58
+ ```console
59
+ $ host-pressure
60
+ CPU 16% MEM 72% SWAP 1.5G pressure normal
61
+ ```
62
+
63
+ ```console
64
+ $ host-pressure check
65
+ ok
66
+ ```
67
+
68
+ ```console
69
+ $ host-pressure --format '{level} | CPU {cpu} | MEM {mem}'
70
+ ok | CPU 16% | MEM 72%
71
+ ```
72
+
73
+ ```console
74
+ $ host-pressure check --memory-busy 60
75
+ busy: memory 72% >= 60%
76
+ ```
77
+
78
+ `check` exits **0** for `ok`, **1** for `busy`, and **2** for `overloaded`. The last command exits 1 because it lowers the memory threshold to 60%.
79
+
80
+ ## Why
81
+
82
+ Before you start another build, a memory percentage alone leaves you guessing. `host-pressure check` combines CPU, memory, load per core, disk usage, and the pressure signals your operating system exposes. You get a verdict and the readings that caused it.
83
+
84
+ Use `top` or `htop` when you need to find the process using resources. Use `psutil` when you need a general process-management library. Use this command when a script needs an exit code, a status bar needs one line, or you need macOS memory pressure and Linux PSI alongside ordinary usage figures.
85
+
86
+ ## Measurements
87
+
88
+ ### Repeated calls without waiting
89
+
90
+ For a status bar or a script that must return immediately, use `--no-sample`. It still reads and updates the CPU baseline; if counters have not advanced, CPU prints `n/a` instead of waiting. These are the same flag and 3-warmup/30-run method on all three hosts, measured 2026-11-17. Peak RSS comes from separate `/usr/bin/time` calls.
91
+
92
+ | Host / CPU | Command | Mean (ms) | Peak RSS (MiB) |
93
+ |---|---|---:|---:|
94
+ | macOS / Apple M5 Pro | `python3 -m host_pressure --no-sample` | 52.5 | 20.8 |
95
+ | macOS / Apple M5 Pro | Rust `host-pressure --no-sample` | 5.2 | 9.7 |
96
+ | OCI A1 / aarch64¹ | `python -m host_pressure --no-sample` | 70.0 | 15.3 |
97
+ | OCI A1 / aarch64¹ | Rust `host-pressure --no-sample` | 1.6 | 2.1 |
98
+ | Windows 11 / Ryzen 7 PRO 6850U | `python -m host_pressure --no-sample` | 166.2 | —² |
99
+ | Windows 11 / Ryzen 7 PRO 6850U | Rust `host-pressure.exe --no-sample` | 22.4 | —² |
100
+
101
+ ¹ The A1 architecture was observed; its CPU model was not verified in this run. ² Windows timings include the venv launcher. Its peak working set excludes the Python child, so those memory readings are not comparable and are omitted.
102
+
103
+ <picture>
104
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/no-sample-dark.svg">
105
+ <img src="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/no-sample-light.svg" alt="Mean --no-sample call times from the saved 30-run measurements" width="880">
106
+ </picture>
107
+
108
+ ```sh
109
+ # macOS: from the source checkout; no CPU sampling wait
110
+ PYTHONPATH=src hyperfine --warmup 3 --runs 30 \
111
+ --export-json docs/bench/m5-no-sample.json \
112
+ 'python3 -m host_pressure --no-sample' \
113
+ './rust/target/release/host-pressure --no-sample'
114
+ PYTHONPATH=src /usr/bin/time -l python3 -m host_pressure --no-sample
115
+ /usr/bin/time -l ./rust/target/release/host-pressure --no-sample
116
+ # A1: installed Python package and Rust binary
117
+ python3 docs/bench/a1-no-sample-bench.py
118
+ # Windows: silent temporary venv, removed when finished
119
+ powershell -NoProfile -File docs/bench/windows-bench.ps1 -NoSample
120
+ ```
121
+
122
+ M5 uses Hyperfine 2.0.0, A1 uses a `perf_counter` subprocess loop, and Windows uses PowerShell `Measure-Command`. The saved [runners and raw outputs](docs/bench/) describe each launch method. These are running machines, not isolated CPU benchmarks.
123
+
124
+ ### Default command, including sampling waits
125
+
126
+ With no flag, both editions fall back to a 0.3-second CPU sample when no usable baseline delta exists. A short sample can extend by up to one second while waiting for counters. The earlier default-command runs include those waits:
127
+
128
+ | Host | Python mean (ms) | Rust mean (ms) |
129
+ |---|---:|---:|
130
+ | M5 | 179.7 | 177.5 |
131
+ | A1 | 72.1 | 122.4 |
132
+ | Windows | 164.2 | 22.2 |
133
+
134
+ This is a different workload from `--no-sample`, not a startup-speed comparison. Exact default commands and raw runs are retained in [docs/bench](docs/bench/).
135
+
136
+ On A1, a follow-up run with separate baseline directories explained the reversal: 11 of 30 rapid Rust calls saw **zero new ticks** and used the sample fallback. All 30 Python calls saw a new baseline delta. With **50 ms between Rust calls**, all 30 used the baseline and averaged **2.36 ms per call**, excluding the pause. The source logic uses the same 0.3-second fallback and baseline rules in both editions; no sampling-interval difference was found. See the [recorded diagnosis](docs/bench/a1-default-diagnosis.json).
137
+
138
+ <picture>
139
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/cpu-flow-dark.svg">
140
+ <img src="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/cpu-flow-light.svg" alt="Without new CPU ticks, --no-sample returns n/a while the default command samples" width="880">
141
+ </picture>
142
+
143
+ ## Reference
144
+
145
+ | Command or flag | Result |
146
+ |---|---|
147
+ | `host-pressure --all` | Add load, disk, thermal, battery and PSI where available |
148
+ | `host-pressure --json` | Full reading and verdict as JSON |
149
+ | `host-pressure check --json` | Verdict and reasons as JSON |
150
+ | `host-pressure --watch 2` | Repeat every two seconds; Ctrl+C stops it |
151
+ | `host-pressure wait --until ok --timeout 120` | Wait for room; exit 75 on timeout |
152
+ | `--format TEMPLATE` / `--format-help` | Select fields; values already include units |
153
+ | `--disk MOUNT` | Read a mount; repeat for more than one |
154
+ | `--sample 0.5` | Take a CPU sample in this call |
155
+ | `--no-sample` | Never wait for CPU counters |
156
+ | `--consumer ID` / `--state-dir DIR` | Select the CPU baseline and storage directory |
157
+
158
+ `--watch --json` writes one object per line. Without `--watch`, JSON is formatted across multiple lines. Parse JSON rather than the human-readable line.
159
+
160
+ ### Thresholds
161
+
162
+ | Threshold flags | Busy / overloaded defaults |
163
+ |---|---|
164
+ | `--cpu-busy`, `--cpu-overloaded` | 80 / 95 percent |
165
+ | `--memory-busy`, `--memory-overloaded` | 85 / 95 percent |
166
+ | `--load-busy`, `--load-overloaded` | 1 / 2 load per CPU core |
167
+ | `--disk-busy`, `--disk-overloaded` | 90 / 97 percent |
168
+ | `--swap-busy-gb`, `--swap-overloaded-gb` | Disabled |
169
+
170
+ Use `--config FILE`, `HOST_PRESSURE_CONFIG`, or `$XDG_CONFIG_HOME/host-pressure/config.json` for persistent thresholds. Keys use snake case, such as `memory_busy`; unknown keys are errors. Environment overrides use `HOST_PRESSURE_MEMORY_BUSY=80`. Command-line values win over environment values, which win over the file.
171
+
172
+ Config and environment also accept `psi_cpu_busy`, `psi_cpu_overloaded`, `psi_memory_busy`, `psi_memory_overloaded`, `psi_io_busy`, and `psi_io_overloaded`. macOS kernel pressure and thermal states have fixed verdict mappings.
173
+
174
+ CPU baselines live under `$XDG_STATE_HOME/host-pressure`; `HOST_PRESSURE_STATE_DIR` overrides that directory. Give separate callers their own `--consumer` value. The baseline interval is the time between calls, not a fixed sampling window. Rust and Python share its format.
175
+
176
+ ### Python
177
+
178
+ ```python
179
+ import host_pressure
180
+
181
+ reading = host_pressure.read(consumer_id="my-tool")
182
+ result = host_pressure.verdict(reading)
183
+ print(result["level"], result["reasons"])
184
+ ```
185
+
186
+ `read(sample=0.5)` takes an explicit CPU sample. `verdict()` without a reading samples for 0.2 seconds by default; use `verdict(reading)` to classify an existing reading without waiting. The library uses only the Python standard library.
187
+
188
+ ## Limits
189
+
190
+ - Missing readings stay `null` in JSON and `n/a` in text. A missing CPU number does not mean 0% usage.
191
+ - Windows has no load-average or thermal reading. Its pressure verdict comes from memory load.
192
+ - Battery-present readings were not exercised in these runs. Linux virtual machines may expose no thermal zone.
193
+ - A short CPU sample can stretch by up to one second while waiting for counters to move. The first default call may also sample.
194
+ - macOS swap can remain allocated after pressure falls, so swap thresholds are off by default.
195
+ - `--watch` repeats readings; it stores no history and sends no alerts. One `ok` does not describe the machine over time.
196
+ - macOS/Linux x86_64 wheels exist, but those backends were not run here.
197
+
198
+ ## Contributing
199
+
200
+ Issues and platform reports are welcome; run `bash rust/parity.sh` from the source checkout. See [AGENTS.md](AGENTS.md) for the code layout and safety rules.
201
+
202
+ License: [MIT](LICENSE).
203
+
@@ -0,0 +1,177 @@
1
+ # host-pressure
2
+ [한국어](README.ko.md)
3
+
4
+ A command-line resource check that tells you whether your machine has room for another job.
5
+
6
+ <picture>
7
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/demo/dark.gif">
8
+ <img src="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/demo/light.gif" alt="A resource line, an ok verdict, and repeated readings from the labeled demo fixture" width="1200">
9
+ </picture>
10
+
11
+ The recording runs the Python CLI with [synthetic readings](docs/demo/fixture.py). It shows formatting and verdicts, not a measurement of a real host.
12
+
13
+ ## Install
14
+
15
+ ```sh
16
+ pipx install host-pressure
17
+ uv tool install host-pressure
18
+ pip install host-pressure
19
+ ```
20
+
21
+ Python 3.9+. Wheels install the Rust command and the importable Python package. A source install needs Rust.
22
+
23
+ | Platform | Observed runs |
24
+ |---|---|
25
+ | macOS arm64 | Rust command and Python library |
26
+ | Linux arm64 | Rust command and Python library on Ubuntu 24.04 |
27
+ | Windows x64 | Both commands on Windows 11 |
28
+
29
+ ## Quick start
30
+
31
+ You can read one line, check whether to start work, or choose fields for a status bar. These outputs were captured from the demo fixture; your readings will differ.
32
+
33
+ ```console
34
+ $ host-pressure
35
+ CPU 16% MEM 72% SWAP 1.5G pressure normal
36
+ ```
37
+
38
+ ```console
39
+ $ host-pressure check
40
+ ok
41
+ ```
42
+
43
+ ```console
44
+ $ host-pressure --format '{level} | CPU {cpu} | MEM {mem}'
45
+ ok | CPU 16% | MEM 72%
46
+ ```
47
+
48
+ ```console
49
+ $ host-pressure check --memory-busy 60
50
+ busy: memory 72% >= 60%
51
+ ```
52
+
53
+ `check` exits **0** for `ok`, **1** for `busy`, and **2** for `overloaded`. The last command exits 1 because it lowers the memory threshold to 60%.
54
+
55
+ ## Why
56
+
57
+ Before you start another build, a memory percentage alone leaves you guessing. `host-pressure check` combines CPU, memory, load per core, disk usage, and the pressure signals your operating system exposes. You get a verdict and the readings that caused it.
58
+
59
+ Use `top` or `htop` when you need to find the process using resources. Use `psutil` when you need a general process-management library. Use this command when a script needs an exit code, a status bar needs one line, or you need macOS memory pressure and Linux PSI alongside ordinary usage figures.
60
+
61
+ ## Measurements
62
+
63
+ ### Repeated calls without waiting
64
+
65
+ For a status bar or a script that must return immediately, use `--no-sample`. It still reads and updates the CPU baseline; if counters have not advanced, CPU prints `n/a` instead of waiting. These are the same flag and 3-warmup/30-run method on all three hosts, measured 2026-11-17. Peak RSS comes from separate `/usr/bin/time` calls.
66
+
67
+ | Host / CPU | Command | Mean (ms) | Peak RSS (MiB) |
68
+ |---|---|---:|---:|
69
+ | macOS / Apple M5 Pro | `python3 -m host_pressure --no-sample` | 52.5 | 20.8 |
70
+ | macOS / Apple M5 Pro | Rust `host-pressure --no-sample` | 5.2 | 9.7 |
71
+ | OCI A1 / aarch64¹ | `python -m host_pressure --no-sample` | 70.0 | 15.3 |
72
+ | OCI A1 / aarch64¹ | Rust `host-pressure --no-sample` | 1.6 | 2.1 |
73
+ | Windows 11 / Ryzen 7 PRO 6850U | `python -m host_pressure --no-sample` | 166.2 | —² |
74
+ | Windows 11 / Ryzen 7 PRO 6850U | Rust `host-pressure.exe --no-sample` | 22.4 | —² |
75
+
76
+ ¹ The A1 architecture was observed; its CPU model was not verified in this run. ² Windows timings include the venv launcher. Its peak working set excludes the Python child, so those memory readings are not comparable and are omitted.
77
+
78
+ <picture>
79
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/no-sample-dark.svg">
80
+ <img src="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/no-sample-light.svg" alt="Mean --no-sample call times from the saved 30-run measurements" width="880">
81
+ </picture>
82
+
83
+ ```sh
84
+ # macOS: from the source checkout; no CPU sampling wait
85
+ PYTHONPATH=src hyperfine --warmup 3 --runs 30 \
86
+ --export-json docs/bench/m5-no-sample.json \
87
+ 'python3 -m host_pressure --no-sample' \
88
+ './rust/target/release/host-pressure --no-sample'
89
+ PYTHONPATH=src /usr/bin/time -l python3 -m host_pressure --no-sample
90
+ /usr/bin/time -l ./rust/target/release/host-pressure --no-sample
91
+ # A1: installed Python package and Rust binary
92
+ python3 docs/bench/a1-no-sample-bench.py
93
+ # Windows: silent temporary venv, removed when finished
94
+ powershell -NoProfile -File docs/bench/windows-bench.ps1 -NoSample
95
+ ```
96
+
97
+ M5 uses Hyperfine 2.0.0, A1 uses a `perf_counter` subprocess loop, and Windows uses PowerShell `Measure-Command`. The saved [runners and raw outputs](docs/bench/) describe each launch method. These are running machines, not isolated CPU benchmarks.
98
+
99
+ ### Default command, including sampling waits
100
+
101
+ With no flag, both editions fall back to a 0.3-second CPU sample when no usable baseline delta exists. A short sample can extend by up to one second while waiting for counters. The earlier default-command runs include those waits:
102
+
103
+ | Host | Python mean (ms) | Rust mean (ms) |
104
+ |---|---:|---:|
105
+ | M5 | 179.7 | 177.5 |
106
+ | A1 | 72.1 | 122.4 |
107
+ | Windows | 164.2 | 22.2 |
108
+
109
+ This is a different workload from `--no-sample`, not a startup-speed comparison. Exact default commands and raw runs are retained in [docs/bench](docs/bench/).
110
+
111
+ On A1, a follow-up run with separate baseline directories explained the reversal: 11 of 30 rapid Rust calls saw **zero new ticks** and used the sample fallback. All 30 Python calls saw a new baseline delta. With **50 ms between Rust calls**, all 30 used the baseline and averaged **2.36 ms per call**, excluding the pause. The source logic uses the same 0.3-second fallback and baseline rules in both editions; no sampling-interval difference was found. See the [recorded diagnosis](docs/bench/a1-default-diagnosis.json).
112
+
113
+ <picture>
114
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/cpu-flow-dark.svg">
115
+ <img src="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/cpu-flow-light.svg" alt="Without new CPU ticks, --no-sample returns n/a while the default command samples" width="880">
116
+ </picture>
117
+
118
+ ## Reference
119
+
120
+ | Command or flag | Result |
121
+ |---|---|
122
+ | `host-pressure --all` | Add load, disk, thermal, battery and PSI where available |
123
+ | `host-pressure --json` | Full reading and verdict as JSON |
124
+ | `host-pressure check --json` | Verdict and reasons as JSON |
125
+ | `host-pressure --watch 2` | Repeat every two seconds; Ctrl+C stops it |
126
+ | `host-pressure wait --until ok --timeout 120` | Wait for room; exit 75 on timeout |
127
+ | `--format TEMPLATE` / `--format-help` | Select fields; values already include units |
128
+ | `--disk MOUNT` | Read a mount; repeat for more than one |
129
+ | `--sample 0.5` | Take a CPU sample in this call |
130
+ | `--no-sample` | Never wait for CPU counters |
131
+ | `--consumer ID` / `--state-dir DIR` | Select the CPU baseline and storage directory |
132
+
133
+ `--watch --json` writes one object per line. Without `--watch`, JSON is formatted across multiple lines. Parse JSON rather than the human-readable line.
134
+
135
+ ### Thresholds
136
+
137
+ | Threshold flags | Busy / overloaded defaults |
138
+ |---|---|
139
+ | `--cpu-busy`, `--cpu-overloaded` | 80 / 95 percent |
140
+ | `--memory-busy`, `--memory-overloaded` | 85 / 95 percent |
141
+ | `--load-busy`, `--load-overloaded` | 1 / 2 load per CPU core |
142
+ | `--disk-busy`, `--disk-overloaded` | 90 / 97 percent |
143
+ | `--swap-busy-gb`, `--swap-overloaded-gb` | Disabled |
144
+
145
+ Use `--config FILE`, `HOST_PRESSURE_CONFIG`, or `$XDG_CONFIG_HOME/host-pressure/config.json` for persistent thresholds. Keys use snake case, such as `memory_busy`; unknown keys are errors. Environment overrides use `HOST_PRESSURE_MEMORY_BUSY=80`. Command-line values win over environment values, which win over the file.
146
+
147
+ Config and environment also accept `psi_cpu_busy`, `psi_cpu_overloaded`, `psi_memory_busy`, `psi_memory_overloaded`, `psi_io_busy`, and `psi_io_overloaded`. macOS kernel pressure and thermal states have fixed verdict mappings.
148
+
149
+ CPU baselines live under `$XDG_STATE_HOME/host-pressure`; `HOST_PRESSURE_STATE_DIR` overrides that directory. Give separate callers their own `--consumer` value. The baseline interval is the time between calls, not a fixed sampling window. Rust and Python share its format.
150
+
151
+ ### Python
152
+
153
+ ```python
154
+ import host_pressure
155
+
156
+ reading = host_pressure.read(consumer_id="my-tool")
157
+ result = host_pressure.verdict(reading)
158
+ print(result["level"], result["reasons"])
159
+ ```
160
+
161
+ `read(sample=0.5)` takes an explicit CPU sample. `verdict()` without a reading samples for 0.2 seconds by default; use `verdict(reading)` to classify an existing reading without waiting. The library uses only the Python standard library.
162
+
163
+ ## Limits
164
+
165
+ - Missing readings stay `null` in JSON and `n/a` in text. A missing CPU number does not mean 0% usage.
166
+ - Windows has no load-average or thermal reading. Its pressure verdict comes from memory load.
167
+ - Battery-present readings were not exercised in these runs. Linux virtual machines may expose no thermal zone.
168
+ - A short CPU sample can stretch by up to one second while waiting for counters to move. The first default call may also sample.
169
+ - macOS swap can remain allocated after pressure falls, so swap thresholds are off by default.
170
+ - `--watch` repeats readings; it stores no history and sends no alerts. One `ok` does not describe the machine over time.
171
+ - macOS/Linux x86_64 wheels exist, but those backends were not run here.
172
+
173
+ ## Contributing
174
+
175
+ Issues and platform reports are welcome; run `bash rust/parity.sh` from the source checkout. See [AGENTS.md](AGENTS.md) for the code layout and safety rules.
176
+
177
+ License: [MIT](LICENSE).
@@ -0,0 +1,53 @@
1
+ [build-system]
2
+ requires = ["maturin>=1.0,<2.0"]
3
+ build-backend = "maturin"
4
+
5
+ [project]
6
+ name = "host-pressure"
7
+ version = "0.1.1"
8
+ description = "A command-line resource check that tells you whether your machine has room for another job."
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "El Fenomeno" }]
14
+ keywords = [
15
+ "cpu",
16
+ "memory",
17
+ "swap",
18
+ "pressure",
19
+ "psi",
20
+ "load",
21
+ "monitoring",
22
+ "health-check",
23
+ "cli",
24
+ "macos",
25
+ "linux",
26
+ "windows",
27
+ ]
28
+ classifiers = [
29
+ "Development Status :: 4 - Beta",
30
+ "Environment :: Console",
31
+ "Intended Audience :: Developers",
32
+ "Intended Audience :: System Administrators",
33
+ "Operating System :: MacOS",
34
+ "Operating System :: Microsoft :: Windows",
35
+ "Operating System :: POSIX :: Linux",
36
+ "Programming Language :: Python :: 3",
37
+ "Programming Language :: Python :: 3 :: Only",
38
+ "Topic :: System :: Monitoring",
39
+ "Topic :: System :: Systems Administration",
40
+ ]
41
+ dependencies = []
42
+
43
+ [project.urls]
44
+ Homepage = "https://github.com/elfenomenokim/host-pressure"
45
+ Repository = "https://github.com/elfenomenokim/host-pressure"
46
+ Issues = "https://github.com/elfenomenokim/host-pressure/issues"
47
+
48
+ [tool.maturin]
49
+ bindings = "bin"
50
+ manifest-path = "rust/Cargo.toml"
51
+ python-source = "src"
52
+ module-name = "host_pressure"
53
+ strip = true
@@ -0,0 +1,16 @@
1
+ # This file is automatically @generated by Cargo.
2
+ # It is not intended for manual editing.
3
+ version = 4
4
+
5
+ [[package]]
6
+ name = "host-pressure"
7
+ version = "0.1.1"
8
+ dependencies = [
9
+ "libc",
10
+ ]
11
+
12
+ [[package]]
13
+ name = "libc"
14
+ version = "0.2.191"
15
+ source = "registry+https://github.com/rust-lang/crates.io-index"
16
+ checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
@@ -0,0 +1,13 @@
1
+ [package]
2
+ name = "host-pressure"
3
+ version = "0.1.1"
4
+ edition = "2021"
5
+ description = "Read CPU, memory, swap, disk, thermal, battery and pressure stall time on macOS, Linux and Windows, and turn them into one verdict: ok, busy or overloaded. No subprocess."
6
+ license = "MIT"
7
+
8
+ [[bin]]
9
+ name = "host-pressure"
10
+ path = "src/main.rs"
11
+
12
+ [target.'cfg(unix)'.dependencies]
13
+ libc = "0.2"
@@ -0,0 +1,23 @@
1
+ import json, sys
2
+ d = json.load(sys.stdin)
3
+ def norm(v):
4
+ if isinstance(v, dict):
5
+ return {k: norm(x) for k, x in sorted(v.items())}
6
+ if isinstance(v, list):
7
+ return [norm(x) for x in v]
8
+ if v is None:
9
+ return None
10
+ if isinstance(v, bool):
11
+ return v
12
+ if isinstance(v, (int, float)):
13
+ return "<num>"
14
+ return "<str>"
15
+ for k in ("observedAt","cpuPercent","memoryPercent","memoryUsedBytes","loadavg","uptime","uptimeSeconds"):
16
+ if k in d:
17
+ d[k] = f"<{type(d[k]).__name__}>"
18
+ if "disks" in d and isinstance(d["disks"], list):
19
+ for disk in d["disks"]:
20
+ for kk in ("usedBytes","freeBytes","percent"):
21
+ if kk in disk:
22
+ disk[kk] = f"<{type(disk[kk]).__name__ if disk[kk] is not None else 'None'}>"
23
+ print(json.dumps(norm(d), sort_keys=True, indent=2))
@@ -0,0 +1,128 @@
1
+ #!/usr/bin/env bash
2
+ # parity.sh — compare Python and Rust host-pressure editions with the same flags.
3
+ # Volatile numbers (CPU %, memory %, timestamps, load) differ between two instants,
4
+ # so they are compared by presence/type, not value. Stable output (keys, formats,
5
+ # exit codes, error messages) must match exactly.
6
+ set -uo pipefail
7
+
8
+ HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
9
+ ROOT="$HERE/.."
10
+ PY="PYTHONPATH=$ROOT/src python3 -m host_pressure"
11
+ RS_BIN="${RS_BIN:-$HERE/target/debug/host-pressure}"
12
+
13
+ if [ ! -x "$RS_BIN" ]; then
14
+ # fall back to release build
15
+ if [ -x "$HERE/target/release/host-pressure" ]; then
16
+ RS_BIN="$HERE/target/release/host-pressure"
17
+ else
18
+ echo "parity: missing Rust binary ($RS_BIN)" >&2
19
+ exit 1
20
+ fi
21
+ fi
22
+
23
+ pass=0
24
+ fail=0
25
+
26
+ ok() { pass=$((pass+1)); echo "ok: $1"; }
27
+ bad() { fail=$((fail+1)); echo "FAIL: $1"; echo "$2" | head -n 20; }
28
+
29
+ # 1. --format-help must be byte-identical.
30
+ if diff -u <(PYTHONPATH="$ROOT/src" python3 -m host_pressure --format-help) <("$RS_BIN" --format-help) > /tmp/hp-parity-help.diff; then
31
+ ok "--format-help identical"
32
+ else
33
+ bad "--format-help differs" "$(cat /tmp/hp-parity-help.diff)"
34
+ fi
35
+
36
+ # 2. --json keys and value shapes (normalize volatile values to types).
37
+ normalize() {
38
+ python3 "$HERE/normalize_json.py"
39
+ }
40
+
41
+ for flags in "--sample 0.1" "--sample 0.1 --all" "--sample 0.1 --disk / --disk /tmp --all"; do
42
+ # shellcheck disable=SC2086
43
+ if diff -u <(PYTHONPATH="$ROOT/src" python3 -m host_pressure --json $flags | normalize) <("$RS_BIN" --json $flags | normalize) > /tmp/hp-parity-json.diff; then
44
+ ok "--json $flags (normalised)"
45
+ else
46
+ bad "--json $flags (normalised)" "$(cat /tmp/hp-parity-json.diff)"
47
+ fi
48
+ done
49
+
50
+ # 3. one-line shape: CPU x% MEM y% SWAP z pressure w (values may differ, shape must hold).
51
+ shape='^CPU (n/a|[0-9]+%) MEM (n/a|[0-9]+%) SWAP (n/a|[0-9.]+[KMGTB]) pressure (normal|warning|critical|unknown)( LOAD .*| DISK .*| THERM .*| BAT .*| PSI .*)*$'
52
+ for flags in "--sample 0.1" "--sample 0.1 --all"; do
53
+ # shellcheck disable=SC2086
54
+ py_line=$(PYTHONPATH="$ROOT/src" python3 -m host_pressure $flags)
55
+ # shellcheck disable=SC2086
56
+ rs_line=$("$RS_BIN" $flags)
57
+ if [[ "$py_line" =~ $shape ]] && [[ "$rs_line" =~ $shape ]]; then
58
+ ok "one-line shape $flags"
59
+ else
60
+ bad "one-line shape $flags" "py: $py_line
61
+ rs: $rs_line"
62
+ fi
63
+ done
64
+
65
+ # 4. check semantics: exit codes 0/1/2 and reason shape.
66
+ # shellcheck disable=SC2086
67
+ PYTHONPATH="$ROOT/src" python3 -m host_pressure check --sample 0.1 >/dev/null; py_code=$?
68
+ "$RS_BIN" check --sample 0.1 >/dev/null; rs_code=$?
69
+ if [ "$py_code" = "$rs_code" ]; then
70
+ ok "check exit code ($py_code)"
71
+ else
72
+ bad "check exit code" "py=$py_code rs=$rs_code"
73
+ fi
74
+
75
+ # forced busy must exit 1 with same reason shape
76
+ py_out=$(PYTHONPATH="$ROOT/src" python3 -m host_pressure check --memory-busy 10 --sample 0.1; echo "exit:$?")
77
+ rs_out=$("$RS_BIN" check --memory-busy 10 --sample 0.1; echo "exit:$?")
78
+ py_reason=$(echo "$py_out" | head -n 1)
79
+ rs_reason=$(echo "$rs_out" | head -n 1)
80
+ if [[ "$py_reason" =~ ^busy:\ memory\ [0-9.]+%\ \>=\ 10%$ ]] && [[ "$rs_reason" =~ ^busy:\ memory\ [0-9.]+%\ \>=\ 10%$ ]]; then
81
+ ok "check busy reason shape"
82
+ else
83
+ bad "check busy reason shape" "py: $py_reason
84
+ rs: $rs_reason"
85
+ fi
86
+
87
+ # 5. error paths: unknown placeholder, unknown key, bad env (exit 64, same message).
88
+ py_err=$(PYTHONPATH="$ROOT/src" python3 -m host_pressure --format 'CPU {bogus}' --sample 0.1 2>&1; echo "exit:$?")
89
+ rs_err=$("$RS_BIN" --format 'CPU {bogus}' --sample 0.1 2>&1; echo "exit:$?")
90
+ if [ "$(echo "$py_err" | tail -n 1)" = "exit:64" ] && [ "$(echo "$rs_err" | tail -n 1)" = "exit:64" ] \
91
+ && [ "$(echo "$py_err" | head -n 1)" = "$(echo "$rs_err" | head -n 1)" ]; then
92
+ ok "unknown placeholder error"
93
+ else
94
+ bad "unknown placeholder error" "py: $py_err
95
+ rs: $rs_err"
96
+ fi
97
+
98
+ tmp_cfg=$(mktemp)
99
+ echo '{"bogus_key": 1}' > "$tmp_cfg"
100
+ py_err=$(PYTHONPATH="$ROOT/src" python3 -m host_pressure --config "$tmp_cfg" --sample 0.1 2>&1; echo "exit:$?")
101
+ rs_err=$("$RS_BIN" --config "$tmp_cfg" --sample 0.1 2>&1; echo "exit:$?")
102
+ rm -f "$tmp_cfg"
103
+ if [ "$(echo "$py_err" | tail -n 1)" = "exit:64" ] && [ "$(echo "$rs_err" | tail -n 1)" = "exit:64" ]; then
104
+ # compare after normalising the config path (same path given, so must match)
105
+ if [ "$(echo "$py_err" | head -n 1)" = "$(echo "$rs_err" | head -n 1)" ]; then
106
+ ok "config unknown key error"
107
+ else
108
+ bad "config unknown key error" "py: $py_err
109
+ rs: $rs_err"
110
+ fi
111
+ else
112
+ bad "config unknown key exit" "py: $py_err
113
+ rs: $rs_err"
114
+ fi
115
+
116
+ # 6. wait timeout semantics: exit 75 with same stderr shape.
117
+ py_err=$(PYTHONPATH="$ROOT/src" python3 -m host_pressure wait --until ok --timeout 0.5 --interval 0.2 --sample 0.1 --memory-busy 1 --memory-overloaded 2 2>&1; echo "exit:$?")
118
+ rs_err=$("$RS_BIN" wait --until ok --timeout 0.5 --interval 0.2 --sample 0.1 --memory-busy 1 --memory-overloaded 2 2>&1; echo "exit:$?")
119
+ if [ "$(echo "$py_err" | tail -n 1)" = "exit:75" ] && [ "$(echo "$rs_err" | tail -n 1)" = "exit:75" ]; then
120
+ ok "wait timeout exit 75"
121
+ else
122
+ bad "wait timeout exit" "py: $py_err
123
+ rs: $rs_err"
124
+ fi
125
+
126
+ echo "---"
127
+ echo "pass=$pass fail=$fail"
128
+ [ "$fail" -eq 0 ]