Metadata-Version: 2.4
Name: nptop
Version: 0.1.0
Summary: An nvitop-like interactive monitor for Ascend NPUs
Author: ZYM-PKU
License-Expression: MIT
Keywords: npu,ascend,monitor,npu-smi,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# nptop

`nptop` 是一个面向华为昇腾 NPU 的轻量级、零 Python 依赖监控工具，提供类似
`nvitop` 的实时设备和进程视图。它调用机器已有的 `npu-smi`，不要求安装 CANN
Python SDK。

![Python](https://img.shields.io/badge/python-3.9%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)

## 功能

- 每张 NPU 独占一行，AICore 利用率与 HBM 占用率均使用彩色进度条
- 展示 NPU 进程、用户、宿主机 CPU/内存、NPU 显存和完整命令行
- 固定高度可滚动视图，启动时位于顶部，支持键盘和鼠标滚轮
- 交互式刷新和按显存、CPU、PID 排序
- 支持单次文本输出和 JSON 输出，方便脚本、巡检与监控系统集成
- 无第三方运行时依赖；兼容容器里的宿主 PID 信息缺失场景
- 对不同 `npu-smi` 版本采用表头和字段语义解析，不依赖固定表格宽度

## 安装

机器需要已安装并可运行 `npu-smi`。

```bash
pip install nptop
nptop
```

从 Git 仓库安装：

```bash
pip install git+https://github.com/ZYM-PKU/nptop.git
```

开发安装：

```bash
git clone https://github.com/ZYM-PKU/nptop.git
cd nptop
python -m pip install -e .
nptop
```

## 使用

```bash
nptop                     # 交互视图，每 2 秒刷新
nptop -i 1                # 每秒刷新（-i 是 interval 的短参数）
nptop -d 0,2,3            # 只看指定 NPU
nptop -1                  # 输出一次后退出
nptop --json              # JSON 快照
nptop --sort cpu          # 进程按 CPU 排序
nptop --raw               # 输出原始 npu-smi，便于兼容性排查
```

交互模式按键：方向键或 `j`/`k` 逐行滚动，`PageUp`/`PageDown` 翻页，
`Home`/`g` 返回顶部，`End`/`G` 到达底部，也支持鼠标滚轮。`q` 退出，`r`
立即刷新，`m` 按 NPU 显存排序，`c` 按 CPU 排序，`p` 按 PID 排序。也可以使用
`Ctrl-C` 退出。

完整参数见：

```bash
nptop --help
```

如果 `npu-smi` 不在 `PATH`，可以显式指定：

```bash
NPUTOP_NPU_SMI=/usr/local/Ascend/driver/tools/npu-smi nptop
```

## 容器说明

容器需要能够执行 `npu-smi`，并挂载相应的昇腾设备和驱动目录。`npu-smi`
返回的宿主机 PID 在容器 PID 命名空间内可能不可见；这时 USER、CPU、宿主机内存
和完整命令会显示为 `?`/`-`，NPU 指标不受影响。

## 开发与发布

```bash
python -m pip install pytest build twine
pytest
python -m build
twine check dist/*
twine upload dist/*
```

发布前请把 `pyproject.toml` 中的 `project.urls` 替换成实际 Git 仓库地址。版本号在
`pyproject.toml` 与 `src/nputop/__init__.py` 中维护。

## 已知范围

当前后端针对华为昇腾 `npu-smi info`。不同驱动大版本如果改变了表格语义，可用
`nptop --raw` 保存输出并提交 issue。项目结构允许后续增加其他 NPU 厂商后端。

## License

MIT
