xputop 0.1.0__tar.gz

xputop-0.1.0/LICENSE

@@ -0,0 +1,92 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form.
+
+      "Work" shall mean the work of authorship made available under the License.
+
+      "Contribution" shall mean any work of authorship submitted to the Licensor
+      for inclusion in the Work.
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of whom
+      a Contribution has been received by the Licensor.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell,
+      import, and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file, You must include
+          a readable copy of the attribution notices contained within
+          such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. The Work is provided on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event shall any Contributor be
+      liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2025 nputop contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

xputop-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+include pyproject.toml
+recursive-include xputop *.py

xputop-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: xputop
+Version: 0.1.0
+Summary: An interactive Huawei Ascend NPU process viewer and monitor, inspired by nvitop.
+Author-email: Zander Zhao <zhaozhaongrui@mails.ucas.ac.cn>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/ZanderZhao/xputop
+Project-URL: Repository, https://github.com/ZanderZhao/xputop
+Project-URL: Issues, https://github.com/ZanderZhao/xputop/issues
+Keywords: huawei,ascend,npu,monitor,top,npu-smi,gpu
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0.0
+Requires-Dist: psutil>=5.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# xputop
+
+An interactive Huawei Ascend NPU process viewer and monitor, inspired by [nvitop](https://github.com/XuehaiPan/nvitop).
+
+## Features
+
+- Real-time monitoring of Huawei Ascend NPU devices (HBM memory, AI Core utilization, temperature, power)
+- Rich terminal UI with per-device cards, usage bars, and process lists
+- **Fixed process row count** per NPU card to prevent UI jitter (`-p N`, default 3)
+- **Sparkline history curves** (like nvtop) for NPU, CPU, memory, disk, and network metrics
+- **Detail mode** (`-d`) for combined chart + CPU + memory + disk view
+- **Full detail mode** (`-a`) adds network I/O monitoring and system process tree
+- **CPU per-core utilization** panel with load averages
+- **System memory** (RAM + Swap) panel
+- **Disk usage** panel with configurable mount points
+- **Network I/O** panel with rate history (auto-skips if root privileges unavailable)
+- Multi-card support with summary table
+- Configurable heartbeat / refresh interval
+- **Threshold-based email alerting** for both NPU and system metrics
+- Configuration stored in `~/.config/xputop/config.toml` (XDG-compliant)
+- **Chinese help** via `--zh`
+- JSON output mode for scripting and automation
+- Demo mode for development without hardware
+- **Lightweight design** — non-blocking CPU sampling, no extra subprocesses
+
+## Installation
+
+```bash
+pip install xputop
+```
+
+## Quick Start
+
+```bash
+# Launch the interactive TUI
+xputop
+
+# Detail mode: chart + CPU + memory + disk
+xputop -d
+
+# Full detail: + network I/O + process tree
+xputop -a
+
+# Show with sparkline curves + CPU + memory + disk
+xputop -C --cpu -m -D
+
+# Control process display rows (default 3, 0=hide, -1=show all)
+xputop -p 5 -C
+xputop -p 0           # hide all processes
+xputop -p -1          # show all (may jitter)
+
+# Monitor specific disk paths
+xputop -C -D /data /home
+
+# Run in demo mode (no Ascend hardware needed)
+xputop --demo -d
+xputop --demo -a
+
+# Set custom refresh interval (seconds)
+xputop -i 5
+
+# Print a single snapshot and exit
+xputop once --cpu --mem --disk
+
+# Print snapshot as JSON
+xputop once --json --cpu --mem --disk /data
+
+# Show Chinese help
+xputop --zh
+
+# Generate a default configuration file
+xputop config --generate
+
+# Send a test alert email
+xputop alert-test
+```
+
+## Command-Line Options
+
+| Short | Long             | Default | Description                                      |
+|-------|------------------|---------|--------------------------------------------------|
+| `-V`  | `--version`      | —       | Show version and exit                            |
+| `-i`  | `--interval`     | 2.0     | Refresh interval in seconds                      |
+| `-c`  | `--config`       | —       | Path to configuration file                       |
+| `-C`  | `--chart`        | off     | Enable nvtop-style sparkline history curves      |
+| `-l`  | `--chart-length` | 120     | Number of history points for sparklines          |
+| `-p`  | `--processes`    | 3       | Process rows per NPU card (0=hide, -1=all)       |
+|       | `--cpu`          | off     | Show CPU per-core utilization panel              |
+| `-m`  | `--mem`          | off     | Show system memory panel                         |
+| `-D`  | `--disk`         | off     | Show disk usage panel (optionally specify paths) |
+| `-d`  | `--detail`       | off     | Detail mode = `--chart --cpu --mem --disk`       |
+| `-a`  | `--detail-all`   | off     | Full detail = `-d` + network + process tree      |
+|       | `--demo`         | off     | Demo mode with fake NPU data                    |
+|       | `--demo-devices` | 4       | Number of simulated NPU devices                 |
+|       | `--zh`           | —       | Show Chinese help                                |
+
+## Configuration
+
+Configuration is stored at `~/.config/xputop/config.toml`. Generate a default:
+
+```bash
+xputop config --generate
+```
+
+You can also set `XPUTOP_CONFIG_DIR` to use a custom directory.
+
+### Example config.toml
+
+```toml
+[general]
+interval = 2.0
+demo = false
+demo_devices = 4
+
+[display]
+chart = true
+chart_length = 120
+cpu = true
+mem = true
+disk = true
+disk_paths = /, /data
+process_rows = 3
+
+[email]
+enabled = true
+smtp_host = smtp.gmail.com
+smtp_port = 587
+use_tls = true
+username = you@gmail.com
+password = your_app_password
+sender = xputop@yourdomain.com
+recipients = admin@yourdomain.com, ops@yourdomain.com
+subject_prefix = [xputop]
+
+# NPU alert rules
+[rule:0]
+metric = temperature
+limit = 80.0
+cooldown = 300
+
+[rule:1]
+metric = hbm_usage_percent
+limit = 95.0
+cooldown = 300
+
+# System alert rules
+[rule:2]
+metric = cpu_percent
+limit = 95.0
+cooldown = 120
+
+[rule:3]
+metric = mem_percent
+limit = 90.0
+cooldown = 300
+
+[rule:4]
+metric = disk_percent
+limit = 95.0
+cooldown = 600
+```
+
+### Alert Rule Metrics
+
+| Metric              | Type   | Description                      | Unit |
+|---------------------|--------|----------------------------------|------|
+| `temperature`       | NPU    | Device temperature               | °C   |
+| `power`             | NPU    | Power consumption                | W    |
+| `aicore_rate`       | NPU    | AI Core utilization              | %    |
+| `hbm_usage_percent` | NPU    | HBM memory usage percentage      | %    |
+| `hbm_used`          | NPU    | HBM memory used                  | MiB  |
+| `cpu_percent`       | System | Overall CPU utilization           | %    |
+| `mem_percent`       | System | RAM usage percentage              | %    |
+| `disk_percent`      | System | Disk usage percentage             | %    |
+| `swap_percent`      | System | Swap usage percentage             | %    |
+
+## Lightweight Design
+
+Designed to run alongside model training with minimal overhead:
+
+- CPU sampling uses psutil non-blocking mode (`cpu_interval=None`), adding zero extra latency
+- All system metrics are collected in a single call — no extra subprocesses
+- Network I/O detection auto-skips if root privileges are unavailable (no retry)
+- Default 2-second heartbeat; recommended 5–10 seconds for heavy training workloads
+- `npu-smi` calls use a 10-second timeout to prevent hangs
+
+## Build & Release
+
+See [BUILD.md](BUILD.md) for development setup, building, and publishing instructions.
+
+## Requirements
+
+- Python >= 3.8
+- Huawei Ascend driver with `npu-smi` in PATH (or use `--demo` mode)
+- `rich` and `psutil` (installed automatically)
+
+## License
+
+Apache License 2.0

xputop-0.1.0/README.md

@@ -0,0 +1,199 @@
+# xputop
+
+An interactive Huawei Ascend NPU process viewer and monitor, inspired by [nvitop](https://github.com/XuehaiPan/nvitop).
+
+## Features
+
+- Real-time monitoring of Huawei Ascend NPU devices (HBM memory, AI Core utilization, temperature, power)
+- Rich terminal UI with per-device cards, usage bars, and process lists
+- **Fixed process row count** per NPU card to prevent UI jitter (`-p N`, default 3)
+- **Sparkline history curves** (like nvtop) for NPU, CPU, memory, disk, and network metrics
+- **Detail mode** (`-d`) for combined chart + CPU + memory + disk view
+- **Full detail mode** (`-a`) adds network I/O monitoring and system process tree
+- **CPU per-core utilization** panel with load averages
+- **System memory** (RAM + Swap) panel
+- **Disk usage** panel with configurable mount points
+- **Network I/O** panel with rate history (auto-skips if root privileges unavailable)
+- Multi-card support with summary table
+- Configurable heartbeat / refresh interval
+- **Threshold-based email alerting** for both NPU and system metrics
+- Configuration stored in `~/.config/xputop/config.toml` (XDG-compliant)
+- **Chinese help** via `--zh`
+- JSON output mode for scripting and automation
+- Demo mode for development without hardware
+- **Lightweight design** — non-blocking CPU sampling, no extra subprocesses
+
+## Installation
+
+```bash
+pip install xputop
+```
+
+## Quick Start
+
+```bash
+# Launch the interactive TUI
+xputop
+
+# Detail mode: chart + CPU + memory + disk
+xputop -d
+
+# Full detail: + network I/O + process tree
+xputop -a
+
+# Show with sparkline curves + CPU + memory + disk
+xputop -C --cpu -m -D
+
+# Control process display rows (default 3, 0=hide, -1=show all)
+xputop -p 5 -C
+xputop -p 0           # hide all processes
+xputop -p -1          # show all (may jitter)
+
+# Monitor specific disk paths
+xputop -C -D /data /home
+
+# Run in demo mode (no Ascend hardware needed)
+xputop --demo -d
+xputop --demo -a
+
+# Set custom refresh interval (seconds)
+xputop -i 5
+
+# Print a single snapshot and exit
+xputop once --cpu --mem --disk
+
+# Print snapshot as JSON
+xputop once --json --cpu --mem --disk /data
+
+# Show Chinese help
+xputop --zh
+
+# Generate a default configuration file
+xputop config --generate
+
+# Send a test alert email
+xputop alert-test
+```
+
+## Command-Line Options
+
+| Short | Long             | Default | Description                                      |
+|-------|------------------|---------|--------------------------------------------------|
+| `-V`  | `--version`      | —       | Show version and exit                            |
+| `-i`  | `--interval`     | 2.0     | Refresh interval in seconds                      |
+| `-c`  | `--config`       | —       | Path to configuration file                       |
+| `-C`  | `--chart`        | off     | Enable nvtop-style sparkline history curves      |
+| `-l`  | `--chart-length` | 120     | Number of history points for sparklines          |
+| `-p`  | `--processes`    | 3       | Process rows per NPU card (0=hide, -1=all)       |
+|       | `--cpu`          | off     | Show CPU per-core utilization panel              |
+| `-m`  | `--mem`          | off     | Show system memory panel                         |
+| `-D`  | `--disk`         | off     | Show disk usage panel (optionally specify paths) |
+| `-d`  | `--detail`       | off     | Detail mode = `--chart --cpu --mem --disk`       |
+| `-a`  | `--detail-all`   | off     | Full detail = `-d` + network + process tree      |
+|       | `--demo`         | off     | Demo mode with fake NPU data                    |
+|       | `--demo-devices` | 4       | Number of simulated NPU devices                 |
+|       | `--zh`           | —       | Show Chinese help                                |
+
+## Configuration
+
+Configuration is stored at `~/.config/xputop/config.toml`. Generate a default:
+
+```bash
+xputop config --generate
+```
+
+You can also set `XPUTOP_CONFIG_DIR` to use a custom directory.
+
+### Example config.toml
+
+```toml
+[general]
+interval = 2.0
+demo = false
+demo_devices = 4
+
+[display]
+chart = true
+chart_length = 120
+cpu = true
+mem = true
+disk = true
+disk_paths = /, /data
+process_rows = 3
+
+[email]
+enabled = true
+smtp_host = smtp.gmail.com
+smtp_port = 587
+use_tls = true
+username = you@gmail.com
+password = your_app_password
+sender = xputop@yourdomain.com
+recipients = admin@yourdomain.com, ops@yourdomain.com
+subject_prefix = [xputop]
+
+# NPU alert rules
+[rule:0]
+metric = temperature
+limit = 80.0
+cooldown = 300
+
+[rule:1]
+metric = hbm_usage_percent
+limit = 95.0
+cooldown = 300
+
+# System alert rules
+[rule:2]
+metric = cpu_percent
+limit = 95.0
+cooldown = 120
+
+[rule:3]
+metric = mem_percent
+limit = 90.0
+cooldown = 300
+
+[rule:4]
+metric = disk_percent
+limit = 95.0
+cooldown = 600
+```
+
+### Alert Rule Metrics
+
+| Metric              | Type   | Description                      | Unit |
+|---------------------|--------|----------------------------------|------|
+| `temperature`       | NPU    | Device temperature               | °C   |
+| `power`             | NPU    | Power consumption                | W    |
+| `aicore_rate`       | NPU    | AI Core utilization              | %    |
+| `hbm_usage_percent` | NPU    | HBM memory usage percentage      | %    |
+| `hbm_used`          | NPU    | HBM memory used                  | MiB  |
+| `cpu_percent`       | System | Overall CPU utilization           | %    |
+| `mem_percent`       | System | RAM usage percentage              | %    |
+| `disk_percent`      | System | Disk usage percentage             | %    |
+| `swap_percent`      | System | Swap usage percentage             | %    |
+
+## Lightweight Design
+
+Designed to run alongside model training with minimal overhead:
+
+- CPU sampling uses psutil non-blocking mode (`cpu_interval=None`), adding zero extra latency
+- All system metrics are collected in a single call — no extra subprocesses
+- Network I/O detection auto-skips if root privileges are unavailable (no retry)
+- Default 2-second heartbeat; recommended 5–10 seconds for heavy training workloads
+- `npu-smi` calls use a 10-second timeout to prevent hangs
+
+## Build & Release
+
+See [BUILD.md](BUILD.md) for development setup, building, and publishing instructions.
+
+## Requirements
+
+- Python >= 3.8
+- Huawei Ascend driver with `npu-smi` in PATH (or use `--demo` mode)
+- `rich` and `psutil` (installed automatically)
+
+## License
+
+Apache License 2.0

xputop-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xputop"
+version = "0.1.0"
+description = "An interactive Huawei Ascend NPU process viewer and monitor, inspired by nvitop."
+readme = "README.md"
+license = {text = "Apache-2.0"}
+requires-python = ">=3.8"
+authors = [
+    {name = "Zander Zhao", email = "zhaozhaongrui@mails.ucas.ac.cn"},
+]
+keywords = ["huawei", "ascend", "npu", "monitor", "top", "npu-smi", "gpu"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Environment :: Console :: Curses",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Monitoring",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "rich>=13.0.0",
+    "psutil>=5.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "build",
+    "twine",
+]
+
+[project.urls]
+Homepage = "https://github.com/ZanderZhao/xputop"
+Repository = "https://github.com/ZanderZhao/xputop"
+Issues = "https://github.com/ZanderZhao/xputop/issues"
+
+[project.scripts]
+xputop = "xputop.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["xputop*"]

xputop-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xputop-0.1.0/tests/test_amd.py

@@ -0,0 +1,76 @@
+"""Tests for the AMD rocm-smi / amd-smi backend parsing."""
+
+from xputop.core.backends.amd import AmdBackend
+
+
+def test_rocm_smi_regex(monkeypatch):
+    backend = AmdBackend()
+    backend._cmd = "rocm-smi"
+    backend._is_amd_smi = False
+
+    fake_output = """
+============================ ROCm System Management Interface ============================
+====================================== System Info =======================================
+GPU[0]: Temperature (Sensor edge) (C): 65.0
+GPU[0]: GPU use (%): 99
+GPU[0]: Average Graphics Package Power (W): 300.5
+GPU[0]: VRAM Total Memory (B): 17163091968
+GPU[0]: VRAM Total Used Memory (B): 8581545984
+GPU[1]: Temperature (Sensor edge) (C): 62.0
+GPU[1]: GPU use (%): 45
+GPU[1]: Average Graphics Package Power (W): 150.2
+GPU[1]: VRAM Total Memory (B): 17163091968
+GPU[1]: VRAM Total Used Memory (B): 2000000000
+=========================================================================================
+"""
+
+    def mock_run(*args, **kwargs):
+        class Res:
+            returncode = 0
+            stdout = fake_output
+        return Res()
+
+    monkeypatch.setattr("subprocess.run", mock_run)
+
+    devices, driver, err = backend._collect_rocm_smi()
+    assert err == ""
+    assert len(devices) == 2
+
+    d0 = devices[0]
+    assert d0.device_id == 0
+    assert d0.temperature == 65.0
+    assert d0.power == 300.5
+    assert d0.utilization_rate == 99.0
+    assert abs(d0.mem_total - 16368.0) < 1.0  # 17163091968 B ~ 16368 MB
+    assert abs(d0.mem_used - 8184.0) < 1.0
+
+
+def test_amd_smi_csv(monkeypatch):
+    backend = AmdBackend()
+    backend._cmd = "amd-smi"
+    backend._is_amd_smi = True
+
+    fake_output = """gpu,temperature (c),power (w),usage (%),vram total (mb),vram used (mb)
+0,75.0,250.0,100,16384,16384
+1,45.0,80.0,0,16384,1024
+"""
+
+    def mock_run(*args, **kwargs):
+        class Res:
+            returncode = 0
+            stdout = fake_output
+        return Res()
+
+    monkeypatch.setattr("subprocess.run", mock_run)
+
+    devices, driver, err = backend._collect_amd_smi()
+    assert err == ""
+    assert len(devices) == 2
+
+    d1 = devices[1]
+    assert d1.device_id == 1
+    assert d1.temperature == 45.0
+    assert d1.power == 80.0
+    assert d1.utilization_rate == 0.0
+    assert d1.mem_total == 16384.0
+    assert d1.mem_used == 1024.0