xpustat 0.1.0__tar.gz

xpustat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Salah Eddine Bekhouche, Hichem Telli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xpustat-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: xpustat
+Version: 0.1.0
+Summary: A unified stat tool for NVIDIA, AMD, Intel, Huawei, Hygon, Cambricon and Moore Threads accelerators
+Author: Salah Eddine Bekhouche, Hichem Telli
+Author-email: bekhouchesalah@gmail.com
+License: MIT
+Project-URL: Homepage, https://github.com/Bekhouche/xpustat
+Keywords: gpu,npu,accelerator,monitoring,nvidia,amd,intel,huawei,ascend
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil>=5.9
+Provides-Extra: nvidia
+Requires-Dist: pynvml>=11.0; extra == "nvidia"
+Provides-Extra: amd
+Requires-Dist: amdsmi; extra == "amd"
+Provides-Extra: fast
+Requires-Dist: pynvml>=11.0; extra == "fast"
+Requires-Dist: amdsmi; extra == "fast"
+Dynamic: license-file
+
+# xpustat
+
+[![GitHub](https://img.shields.io/badge/GitHub-Bekhouche%2Fxpustat-blue?logo=github)](https://github.com/Bekhouche/xpustat)
+**Authors:** Salah Eddine Bekhouche, Hichem Telli
+
+A unified accelerator stat tool — think `gpustat`, but for every vendor.
+
+## Supported backends
+
+| Status | Vendor | Device | CLI tool | Filter key |
+|:---:|---|---|---|---|
+| ✅ Tested | AMD | Radeon RX 7900 XTX (gfx1100) | `amd-smi` | `amd` |
+| ✅ Tested | NVIDIA | NVIDIA L4 (cc8.9), TITAN V (cc7.0) | `nvidia-smi` | `nvidia` |
+| 🔲 Untested | Intel | Gaudi / Gaudi 2 / Gaudi 3 | `hl-smi` | `gaudi` |
+| 🔲 Untested | Intel | Arc / Data Center GPU | `xpu-smi` | `intel` |
+| ✅ Tested | Huawei | Ascend 910B2 | `ascend-dmi` / `npu-smi` | `huawei` |
+| 🔲 Untested | Hygon | DCU | `hy-smi` | `hygon` |
+| 🔲 Untested | Cambricon | MLU | `cnmon` | `cambricon` |
+| 🔲 Untested | Moore Threads | MTT GPU | `mthreads-gmi` | `moorethreads` |
+
+> **Legend:** ✅ Tested on real hardware — 🔲 Implemented, awaiting hardware test
+>
+> Backends whose management tool is not installed are silently skipped.
+
+### Running Vendor Hardware Tests
+
+If you have access to specific hardware, you can help us verify the implementation by running the standalone test scripts found in the `vendor_devices_tests/` directory:
+
+```bash
+# Example: Testing the Huawei backend on a machine with Ascend NPUs
+python vendor_devices_tests/test_huawei.py
+
+# Example: Testing the NVIDIA backend
+python vendor_devices_tests/test_nvidia.py
+```
+If the test successfully outputs your hardware metrics, please let us know so we can update the backend status to **✅ Tested**!
+
+## Install
+
+**pip**
+```bash
+pip install xpustat
+```
+
+**conda**
+```bash
+conda install -c conda-forge xpustat
+```
+
+## CLI usage
+
+```
+xpustat                      # coloured table of all detected devices
+xpustat -pui                 # watch mode, showing processes (-p), users (-u), refreshing every 1.0s (-i)
+xpustat -i 2                 # watch mode, refresh every 2 seconds
+xpustat -i 1 -n 10           # 10 refreshes then exit
+xpustat -a                   # show everything (util, temp, power, arch, user, pid, cmd)
+xpustat -f nvidia amd        # show only NVIDIA and AMD
+xpustat --no-color           # plain text, no ANSI codes
+xpustat --json               # raw JSON output
+xpustat --version
+```
+
+Example output:
+
+```
+xpustat 0.1.0  ·  myhost  ·  Fri May 22  11:24:00  2026
+──────────────────────────────────────────────────────────────────────────
+[NVIDIA] #0    Tesla V100                          │   1,024 / 32,768 MB   ███░░░░░░░░░░░░░    3%
+[AMD   ] #0    Radeon RX 7900 XTX                  │      26 / 24,560 MB   ░░░░░░░░░░░░░░░░    0%
+[HUAWEI] #0:0  Ascend 310                          │   2,703 /  8,192 MB   █████░░░░░░░░░░░   33%
+```
+
+Example output with processes, users, and watch mode (`xpustat -pui`):
+
+```
+xpustat 0.1.0  ·  salah-amd  ·  Fri May 29  10:07:57  2026
+──────────────────────────────────────────────────────────
+[AMD   ] #0    Radeon RX 7900 XTX              │  17,918 / 24,560 MB  ████████████░░░░   72%
+              └─ salah/348504(17480M)
+  refreshing every 1.0s  ·  Ctrl+C to quit
+```
+
+## Python API
+
+```python
+import xpustat
+
+# Query everything at once (parallel by default)
+stats = xpustat.query_all()
+
+print(stats)                      # XPUStatCollection(nvidia=0, amd=1, ...)
+print(stats.amd[0].name)          # "Radeon RX 7900 XTX"
+print(stats.amd[0].mem_used_mb)   # 26
+
+# As a dict (JSON-serialisable)
+import json
+print(json.dumps(stats.to_dict(), indent=2))
+
+# Query a single vendor
+from xpustat import NvidiaGPUStatCollection
+gpus = NvidiaGPUStatCollection.new_query()
+```
+
+## Version history
+
+### 0.1.0
+- Initial release
+- Support for NVIDIA, AMD, Intel Gaudi, Intel Arc/GPU, Huawei Ascend, Hygon DCU, Cambricon MLU, Moore Threads

xpustat-0.1.0/README.md

@@ -0,0 +1,109 @@
+# xpustat
+
+[![GitHub](https://img.shields.io/badge/GitHub-Bekhouche%2Fxpustat-blue?logo=github)](https://github.com/Bekhouche/xpustat)
+**Authors:** Salah Eddine Bekhouche, Hichem Telli
+
+A unified accelerator stat tool — think `gpustat`, but for every vendor.
+
+## Supported backends
+
+| Status | Vendor | Device | CLI tool | Filter key |
+|:---:|---|---|---|---|
+| ✅ Tested | AMD | Radeon RX 7900 XTX (gfx1100) | `amd-smi` | `amd` |
+| ✅ Tested | NVIDIA | NVIDIA L4 (cc8.9), TITAN V (cc7.0) | `nvidia-smi` | `nvidia` |
+| 🔲 Untested | Intel | Gaudi / Gaudi 2 / Gaudi 3 | `hl-smi` | `gaudi` |
+| 🔲 Untested | Intel | Arc / Data Center GPU | `xpu-smi` | `intel` |
+| ✅ Tested | Huawei | Ascend 910B2 | `ascend-dmi` / `npu-smi` | `huawei` |
+| 🔲 Untested | Hygon | DCU | `hy-smi` | `hygon` |
+| 🔲 Untested | Cambricon | MLU | `cnmon` | `cambricon` |
+| 🔲 Untested | Moore Threads | MTT GPU | `mthreads-gmi` | `moorethreads` |
+
+> **Legend:** ✅ Tested on real hardware — 🔲 Implemented, awaiting hardware test
+>
+> Backends whose management tool is not installed are silently skipped.
+
+### Running Vendor Hardware Tests
+
+If you have access to specific hardware, you can help us verify the implementation by running the standalone test scripts found in the `vendor_devices_tests/` directory:
+
+```bash
+# Example: Testing the Huawei backend on a machine with Ascend NPUs
+python vendor_devices_tests/test_huawei.py
+
+# Example: Testing the NVIDIA backend
+python vendor_devices_tests/test_nvidia.py
+```
+If the test successfully outputs your hardware metrics, please let us know so we can update the backend status to **✅ Tested**!
+
+## Install
+
+**pip**
+```bash
+pip install xpustat
+```
+
+**conda**
+```bash
+conda install -c conda-forge xpustat
+```
+
+## CLI usage
+
+```
+xpustat                      # coloured table of all detected devices
+xpustat -pui                 # watch mode, showing processes (-p), users (-u), refreshing every 1.0s (-i)
+xpustat -i 2                 # watch mode, refresh every 2 seconds
+xpustat -i 1 -n 10           # 10 refreshes then exit
+xpustat -a                   # show everything (util, temp, power, arch, user, pid, cmd)
+xpustat -f nvidia amd        # show only NVIDIA and AMD
+xpustat --no-color           # plain text, no ANSI codes
+xpustat --json               # raw JSON output
+xpustat --version
+```
+
+Example output:
+
+```
+xpustat 0.1.0  ·  myhost  ·  Fri May 22  11:24:00  2026
+──────────────────────────────────────────────────────────────────────────
+[NVIDIA] #0    Tesla V100                          │   1,024 / 32,768 MB   ███░░░░░░░░░░░░░    3%
+[AMD   ] #0    Radeon RX 7900 XTX                  │      26 / 24,560 MB   ░░░░░░░░░░░░░░░░    0%
+[HUAWEI] #0:0  Ascend 310                          │   2,703 /  8,192 MB   █████░░░░░░░░░░░   33%
+```
+
+Example output with processes, users, and watch mode (`xpustat -pui`):
+
+```
+xpustat 0.1.0  ·  salah-amd  ·  Fri May 29  10:07:57  2026
+──────────────────────────────────────────────────────────
+[AMD   ] #0    Radeon RX 7900 XTX              │  17,918 / 24,560 MB  ████████████░░░░   72%
+              └─ salah/348504(17480M)
+  refreshing every 1.0s  ·  Ctrl+C to quit
+```
+
+## Python API
+
+```python
+import xpustat
+
+# Query everything at once (parallel by default)
+stats = xpustat.query_all()
+
+print(stats)                      # XPUStatCollection(nvidia=0, amd=1, ...)
+print(stats.amd[0].name)          # "Radeon RX 7900 XTX"
+print(stats.amd[0].mem_used_mb)   # 26
+
+# As a dict (JSON-serialisable)
+import json
+print(json.dumps(stats.to_dict(), indent=2))
+
+# Query a single vendor
+from xpustat import NvidiaGPUStatCollection
+gpus = NvidiaGPUStatCollection.new_query()
+```
+
+## Version history
+
+### 0.1.0
+- Initial release
+- Support for NVIDIA, AMD, Intel Gaudi, Intel Arc/GPU, Huawei Ascend, Hygon DCU, Cambricon MLU, Moore Threads

xpustat-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xpustat"
+version = "0.1.0"
+description = "A unified stat tool for NVIDIA, AMD, Intel, Huawei, Hygon, Cambricon and Moore Threads accelerators"
+readme = "README.md"
+authors = [
+    { name = "Salah Eddine Bekhouche" },
+    { name = "Hichem Telli" },
+    { email = "bekhouchesalah@gmail.com" },
+]
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = ["psutil>=5.9"]
+keywords = ["gpu", "npu", "accelerator", "monitoring", "nvidia", "amd", "intel", "huawei", "ascend"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Monitoring",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.optional-dependencies]
+# Native SDK backends — faster than subprocess, no extra build tools needed
+nvidia = ["pynvml>=11.0"]
+amd    = ["amdsmi"]
+# Install everything at once: pip install xpustat[fast]
+fast   = ["pynvml>=11.0", "amdsmi"]
+
+[project.scripts]
+xpustat = "xpustat.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Bekhouche/xpustat"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["xpustat*"]

xpustat-0.1.0/setup.cfg

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

xpustat-0.1.0/tests/test_cli.py

@@ -0,0 +1,44 @@
+import pytest
+from unittest.mock import patch, MagicMock
+from xpustat import cli
+import argparse
+
+@patch("xpustat.cli._render")
+def test_print_xpustat_snapshot(mock_render):
+    cli.print_xpustat()
+    mock_render.assert_called_once()
+    args = mock_render.call_args[1]
+    assert args["filter_vendors"] is None
+    assert args["show_util"] is False
+
+@patch("xpustat.cli._render")
+@patch("time.sleep", return_value=None)
+@patch("time.monotonic", side_effect=[0, 1, 2, 3])
+def test_print_xpustat_watch_mode(mock_monotonic, mock_sleep, mock_render):
+    cli.print_xpustat(interval=1.0, count=2)
+    assert mock_render.call_count == 2
+
+def test_fields_extract():
+    class DummyDev:
+        name = "TestDev"
+        processes = []
+    
+    idx, name, arch, used, tot, util, temp, pwr, procs = cli._fields("unknown", DummyDev())
+    assert idx == "?"
+    assert name.startswith("<") or "TestDev" in name
+    assert used == 0
+    assert tot == 0
+
+def test_mem_bar():
+    # used=500, total=1000 => 50%
+    bar = cli._mem_bar("32", 500, 1000)
+    assert "█" in bar
+    assert "░" in bar
+
+def test_fmt_cc():
+    assert cli._fmt_cc("8.6") == "cc8.6"
+    assert cli._fmt_cc(None) is None
+
+def test_fmt_gfx():
+    assert cli._fmt_gfx("gfx1100") == "gfx1100"
+    assert cli._fmt_gfx(None) is None

xpustat-0.1.0/tests/test_process.py

@@ -0,0 +1,49 @@
+import pytest
+from unittest.mock import patch, MagicMock
+from xpustat._process import ProcessInfo, enrich_process
+import psutil
+
+def test_process_info():
+    p = ProcessInfo(pid=1234, username="testuser", command="python script.py", gpu_mem_mb=500)
+    assert p.pid == 1234
+    assert p.username == "testuser"
+    assert p.command == "python script.py"
+    assert p.gpu_mem_mb == 500
+    
+    d = p.to_dict()
+    assert d["pid"] == 1234
+    assert d["username"] == "testuser"
+    assert d["command"] == "python script.py"
+    assert d["gpu_mem_mb"] == 500
+    
+    assert repr(p) == "testuser:python script.py/1234(500M)"
+
+@patch("psutil.Process")
+def test_enrich_process_success(mock_process_cls):
+    mock_proc = MagicMock()
+    mock_proc.username.return_value = "mockuser"
+    mock_proc.cmdline.return_value = ["/usr/bin/python", "app.py"]
+    mock_process_cls.return_value = mock_proc
+    
+    username, command = enrich_process(9999, "fallback")
+    assert username == "mockuser"
+    assert command == "python"
+
+@patch("psutil.Process")
+def test_enrich_process_access_denied(mock_process_cls):
+    mock_proc = MagicMock()
+    mock_proc.username.return_value = "mockuser"
+    mock_proc.cmdline.side_effect = psutil.AccessDenied()
+    mock_process_cls.return_value = mock_proc
+    
+    username, command = enrich_process(9999, "fallback")
+    assert username == "mockuser"
+    assert command == "fallback"
+
+@patch("psutil.Process")
+def test_enrich_process_no_process(mock_process_cls):
+    mock_process_cls.side_effect = psutil.NoSuchProcess(9999)
+    
+    username, command = enrich_process(9999, "fallback")
+    assert username == "?"
+    assert command == "fallback"

xpustat-0.1.0/tests/test_vendors.py

@@ -0,0 +1,110 @@
+import pytest
+from xpustat.nvidia import NvidiaGPUStat, NvidiaGPUStatCollection
+from xpustat.amd import AMDGPUStat, AMDGPUStatCollection
+from xpustat.gaudi import GaudiAIPStat, GaudiAIPStatCollection
+from xpustat.intel_gpu import IntelGPUStat, IntelGPUStatCollection
+from xpustat.huawei import HuaweiNPUStat, HuaweiNPUStatCollection
+from xpustat.hygon import HygonDCUStat, HygonDCUStatCollection
+from xpustat.cambricon import CambriconMLUStat, CambriconMLUStatCollection
+from xpustat.moorethreads import MooreThreadsGPUStat, MooreThreadsGPUStatCollection
+
+def test_nvidia_stat():
+    stat = NvidiaGPUStat(
+        gpu_index=0,
+        uuid="GPU-12345",
+        name="Mock Nvidia",
+        mem_used_mb=1000,
+        mem_total_mb=8000,
+        util_pct=50,
+        temp_c=45,
+        power_w=120.0,
+        cuda_cc="8.6",
+        processes=[]
+    )
+    col = NvidiaGPUStatCollection([stat])
+    assert len(col) == 1
+    d = col.to_dict()
+    assert len(d["gpus"]) == 1
+    assert d["gpus"][0]["name"] == "Mock Nvidia"
+
+def test_amd_stat():
+    stat = AMDGPUStat(
+        gpu_index=0,
+        name="Mock AMD",
+        mem_used_mb=2000,
+        mem_total_mb=16000,
+        util_pct=80,
+        temp_c=65,
+        power_w=200.0,
+        gfx_target="gfx1100"
+    )
+    col = AMDGPUStatCollection([stat])
+    assert len(col) == 1
+    d = col.to_dict()
+    assert len(d["gpus"]) == 1
+
+def test_gaudi_stat():
+    stat = GaudiAIPStat(
+        aip_index=0,
+        name="Gaudi2",
+        mem_used_mb=5000,
+        mem_total_mb=32000
+    )
+    col = GaudiAIPStatCollection([stat])
+    assert len(col) == 1
+
+def test_intel_stat():
+    stat = IntelGPUStat(
+        device_id=0,
+        name="Intel Arc",
+        mem_used_mb=1000,
+        mem_total_mb=8000
+    )
+    col = IntelGPUStatCollection([stat])
+    assert len(col) == 1
+
+def test_huawei_stat():
+    stat = HuaweiNPUStat(
+        npu_id=0,
+        chip_id=0,
+        name="Ascend 910B",
+        mem_used_mb=2000,
+        mem_total_mb=32000,
+        ai_core_pct=50,
+        temp_c=40,
+        power_w=150.0,
+        health="OK"
+    )
+    col = HuaweiNPUStatCollection([stat])
+    assert len(col) == 1
+
+def test_hygon_stat():
+    stat = HygonDCUStat(
+        card_index=0,
+        name="Hygon DCU",
+        mem_used_mb=1000,
+        mem_total_mb=16000
+    )
+    col = HygonDCUStatCollection([stat])
+    assert len(col) == 1
+
+def test_cambricon_stat():
+    stat = CambriconMLUStat(
+        card_id=0,
+        chip_id=0,
+        name="Cambricon MLU",
+        mem_used_mb=1000,
+        mem_total_mb=16000
+    )
+    col = CambriconMLUStatCollection([stat])
+    assert len(col) == 1
+
+def test_moorethreads_stat():
+    stat = MooreThreadsGPUStat(
+        gpu_id=0,
+        name="MTT S80",
+        mem_used_mb=1000,
+        mem_total_mb=16000
+    )
+    col = MooreThreadsGPUStatCollection([stat])
+    assert len(col) == 1

xpustat-0.1.0/tests/test_xpu.py

@@ -0,0 +1,78 @@
+import pytest
+import datetime
+import json
+from xpustat import xpu
+from xpustat.xpu import XPUStatCollection
+from xpustat.nvidia import NvidiaGPUStatCollection
+from xpustat.amd import AMDGPUStatCollection
+from xpustat.gaudi import GaudiAIPStatCollection
+from xpustat.intel_gpu import IntelGPUStatCollection
+from xpustat.huawei import HuaweiNPUStatCollection
+from xpustat.hygon import HygonDCUStatCollection
+from xpustat.cambricon import CambriconMLUStatCollection
+from xpustat.moorethreads import MooreThreadsGPUStatCollection
+
+def create_mock_collection():
+    return XPUStatCollection(
+        nvidia=NvidiaGPUStatCollection([]),
+        amd=AMDGPUStatCollection([]),
+        gaudi=GaudiAIPStatCollection([]),
+        intel=IntelGPUStatCollection([]),
+        huawei=HuaweiNPUStatCollection([]),
+        hygon=HygonDCUStatCollection([]),
+        cambricon=CambriconMLUStatCollection([]),
+        moorethreads=MooreThreadsGPUStatCollection([]),
+    )
+
+def test_xpustat_collection_empty():
+    col = create_mock_collection()
+    assert len(col) == 0
+    assert not bool(col)
+    assert len(list(col)) == 0
+
+def test_xpustat_collection_get_item():
+    col = create_mock_collection()
+    assert isinstance(col["nvidia"], NvidiaGPUStatCollection)
+    assert isinstance(col["amd"], AMDGPUStatCollection)
+    with pytest.raises(KeyError):
+        _ = col["unknown"]
+
+def test_xpustat_collection_to_dict():
+    col = create_mock_collection()
+    d = col.to_dict()
+    assert "nvidia" in d
+    assert "amd" in d
+    assert "moorethreads" in d
+    assert d["nvidia"] == []
+
+def test_xpustat_collection_to_json():
+    col = create_mock_collection()
+    j = col.to_json()
+    assert "nvidia" in json.loads(j)
+    
+    j_meta = col.to_json(metadata=True)
+    d_meta = json.loads(j_meta)
+    assert "hostname" in d_meta
+    assert "query_time" in d_meta
+    assert "xpustat_version" in d_meta
+    assert "devices" in d_meta
+
+def test_query_all(monkeypatch):
+    # Mocking new_query on all collections to return empty for testing
+    for name, cls in xpu._BACKENDS:
+        monkeypatch.setattr(cls, "new_query", lambda: cls([]))
+        
+    col = xpu.query_all(parallel=False)
+    assert isinstance(col, XPUStatCollection)
+    assert len(col) == 0
+
+    col_parallel = xpu.query_all(parallel=True)
+    assert isinstance(col_parallel, XPUStatCollection)
+
+def test_query(monkeypatch):
+    monkeypatch.setattr(NvidiaGPUStatCollection, "new_query", lambda: NvidiaGPUStatCollection([]))
+    res = xpu.query("nvidia")
+    assert isinstance(res, NvidiaGPUStatCollection)
+    
+    with pytest.raises(ValueError):
+        xpu.query("unknown")

xpustat-0.1.0/xpustat/__init__.py

@@ -0,0 +1,77 @@
+"""
+xpustat — unified accelerator stat tool.
+
+Supports NVIDIA, AMD, Intel Gaudi, Intel Arc/GPU,
+Huawei Ascend, Hygon DCU, Cambricon MLU, and Moore Threads.
+
+Quick start::
+
+    import xpustat
+
+    # Query all vendors at once
+    stats = xpustat.query_all()
+
+    # Iterate every device across all vendors
+    for dev in stats:
+        print(dev.name, dev.mem_used_mb, "/", dev.mem_total_mb, "MB")
+
+    # Vendor-specific access
+    for gpu in stats.nvidia:
+        print(gpu.name, gpu.util_pct, "%", gpu.temp_c, "°C")
+
+    # Subscript by vendor key
+    for gpu in stats["amd"]:
+        print(gpu.power_w, "W")
+
+    # Query a single vendor
+    gpus = xpustat.query("nvidia")
+
+    # JSON string (for HTTP responses / files)
+    print(stats.to_json(indent=2))
+
+    # JSON with metadata wrapper
+    print(stats.to_json(metadata=True))
+"""
+
+__version__ = "0.1.0"
+__version_tuple__ = (0, 1, 0)
+
+from ._process import ProcessInfo
+from .xpu import AnyDeviceStat, XPUStatCollection, query, query_all
+from .nvidia import NvidiaGPUStat, NvidiaGPUStatCollection
+from .amd import AMDGPUStat, AMDGPUStatCollection
+from .gaudi import GaudiAIPStat, GaudiAIPStatCollection
+from .intel_gpu import IntelGPUStat, IntelGPUStatCollection
+from .huawei import HuaweiNPUStat, HuaweiNPUStatCollection
+from .hygon import HygonDCUStat, HygonDCUStatCollection
+from .cambricon import CambriconMLUStat, CambriconMLUStatCollection
+from .moorethreads import MooreThreadsGPUStat, MooreThreadsGPUStatCollection
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    # Core API
+    "query_all",
+    "query",
+    "XPUStatCollection",
+    "AnyDeviceStat",
+    # Process info
+    "ProcessInfo",
+    # Per-vendor stat objects
+    "NvidiaGPUStat",
+    "NvidiaGPUStatCollection",
+    "AMDGPUStat",
+    "AMDGPUStatCollection",
+    "GaudiAIPStat",
+    "GaudiAIPStatCollection",
+    "IntelGPUStat",
+    "IntelGPUStatCollection",
+    "HuaweiNPUStat",
+    "HuaweiNPUStatCollection",
+    "HygonDCUStat",
+    "HygonDCUStatCollection",
+    "CambriconMLUStat",
+    "CambriconMLUStatCollection",
+    "MooreThreadsGPUStat",
+    "MooreThreadsGPUStatCollection",
+]