hytop 0.1.0__tar.gz

hytop-0.1.0/.gitignore

@@ -0,0 +1,216 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

hytop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 alephpiece
+
+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.

hytop-0.1.0/Makefile

@@ -0,0 +1,39 @@
+.PHONY: help setup format lint test clean bump build
+
+help:
+	@echo "Available targets:"
+	@echo "  make setup           - Create venv, install all dependencies, and set up git hooks"
+	@echo "  make format          - Auto-fix and format code (ruff)"
+	@echo "  make lint            - Check code style and errors without modifying files (ruff)"
+	@echo "  make test            - Run all unit tests (pytest)"
+	@echo "  make clean           - Remove build caches and the virtual environment"
+	@echo "  make bump part=X     - Bump version (patch/minor/major or set X.Y.Z)"
+	@echo "  make build           - Build wheel and sdist into dist/"
+
+setup:
+	@echo ">> Initializing virtual environment and installing dependencies..."
+	uv sync --group dev
+	@echo ">> Installing pre-commit git hooks..."
+	uvx pre-commit install
+
+format:
+	uv run ruff check --fix src/ tests/
+	uv run ruff format src/ tests/
+
+lint:
+	uv run ruff check src/ tests/
+	uv run ruff format --check src/ tests/
+
+test:
+	uv run pytest -v
+
+clean:
+	rm -rf .pytest_cache .ruff_cache .venv
+	find src tests -type f -name "*.pyc" -delete
+	find src tests -type d -name "__pycache__" -delete
+
+bump:
+	uv run python -m hytop._bump $(part)
+
+build:
+	uv build

hytop-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: hytop
+Version: 0.1.0
+Summary: Lightweight monitoring toolkit for Hygon DCU clusters
+Project-URL: Homepage, https://github.com/alephpiece/hg-misc-tools
+Project-URL: Repository, https://github.com/alephpiece/hg-misc-tools
+Project-URL: Issues, https://github.com/alephpiece/hg-misc-tools/issues
+Author-email: alephpiece <wangan.cs@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: dcu,gpu,hygon,hytop,monitoring
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: rich>=14
+Requires-Dist: typer>=0.23
+Description-Content-Type: text/markdown
+
+# hytop - monitoring tools
+
+## Quick start
+
+uv:
+
+```bash
+uv run hytop --help
+```
+
+pip:
+
+```bash
+pip install .
+hytop --help
+```
+
+pipx:
+
+```bash
+pipx install .
+hytop --help
+```
+
+## Prerequisites
+
+- Python >= 3.10
+- Python packages: `rich`, `typer`
+- Passwordless SSH for remote 
+
+## `hytop`
+
+```bash
+# Show the version number
+hytop --version
+
+# Specify a timeout for the subcommand
+hytop --timeout 300 [COMMAND]
+
+# 0.5-second interval and 5-second rolling window for the subcommand
+hytop -n 0.5 --window 5 [COMMAND]
+
+# Specify a list of nodes for the subcommand
+hytop -H node01,node02 [COMMAND]
+```
+
+## `hytop gpu`
+
+A lightweight script for live `hy-smi` polling with rolling averages across multiple hosts. It features a modern terminal UI and can be used as a blocking scheduler for GPU jobs.
+
+### Usage
+
+Simple examples:
+
+```bash
+# Local node, all GPUs
+hytop gpu
+
+# Two nodes, 0.5-second interval
+hytop -H node01,node02 -n 0.5 gpu
+
+# Exit with code 0 when all monitored GPUs are available
+hytop gpu --devices 0,1 --wait-idle
+
+# Wait for GPUs to be idle for 30 seconds before exiting
+hytop gpu --devices 0,1 --wait-idle --wait-idle-seconds 30
+
+# Wait at most 300s for availability (exit 124 on timeout)
+hytop gpu --devices 0,1 --wait-idle --timeout 300
+
+# Fine-grained columns (output order follows show-flag order)
+hytop gpu --showtemp --showpower
+hytop gpu --showpower --showtemp
+```
+
+Queue jobs in shared environments:
+
+```bash
+if hytop -H node01,node02 gpu --timeout 300 --wait-idle; then
+  echo "GPUs available, starting workload..."
+  # YOUR COMMAND HERE (e.g., python train.py)
+else
+  echo "Error: GPUs not available in time, aborting pipeline."
+fi
+```
+
+### Exit Codes
+
+Designed to be script-friendly:
+
+* `0`: Availability condition met (GPUs are idle).
+* `124`: Timeout reached before the availability condition was met.
+* `130`: Interrupted by the user (Ctrl+C).
+* `2`: Argument or input error.
+
+### Fine-grained metric flags
+
+`hytop gpu` uses formatted `hy-smi --json` output and supports a subset of `hy-smi` `--show*` flags:
+
+- `--showtemp`: GPU core temperature (`Temp`)
+- `--showpower`: average package power (`AvgPwr`, plus `AvgPwr@window`)
+- `--showsclk`: sclk frequency (`sclk`)
+- `--showmemuse`: VRAM usage (`VRAM%`)
+- `--showuse`: GPU utilization (`GPU%`, plus `GPU%@window`)
+
+If no `--show*` flags are specified, hytop defaults to:
+`--showtemp --showpower --showsclk --showmemuse --showuse`.
+
+## Development
+
+Clone the repo and run `make setup` to create the virtual environment, install all dependencies (including dev), and configure pre-commit hooks:
+
+```bash
+make setup
+```
+
+Common development commands:
+
+```bash
+make format     # Auto-fix and format code (ruff)
+make lint       # Check code style and errors without modifying files
+make test       # Run all unit tests (pytest)
+make bump part=patch  # Bump version (patch/minor/major or X.Y.Z)
+make clean      # Remove build caches and the virtual environment
+```
+
+### Version bump
+
+Version is sourced from `src/hytop/__init__.py` (`__version__`).
+
+```bash
+make bump part=patch          # 0.1.0 -> 0.1.1
+make bump part=minor          # 0.1.1 -> 0.2.0
+make bump part=major          # 0.2.0 -> 1.0.0
+make bump part="set 1.2.3"   # set an explicit version
+```
+
+### Publish
+
+Releases are automatically published to PyPI when pushing a version tag:
+
+```bash
+# Bump version and commit
+make bump part=patch
+git commit -am "Bump version to 0.1.1"
+
+# Tag and push to trigger GitHub Actions release
+git tag hytop-0.1.1
+git push origin hytop-0.1.1
+```
+
+To test building distributions locally:
+
+```bash
+make build
+```

hytop-0.1.0/README.md

@@ -0,0 +1,156 @@
+# hytop - monitoring tools
+
+## Quick start
+
+uv:
+
+```bash
+uv run hytop --help
+```
+
+pip:
+
+```bash
+pip install .
+hytop --help
+```
+
+pipx:
+
+```bash
+pipx install .
+hytop --help
+```
+
+## Prerequisites
+
+- Python >= 3.10
+- Python packages: `rich`, `typer`
+- Passwordless SSH for remote 
+
+## `hytop`
+
+```bash
+# Show the version number
+hytop --version
+
+# Specify a timeout for the subcommand
+hytop --timeout 300 [COMMAND]
+
+# 0.5-second interval and 5-second rolling window for the subcommand
+hytop -n 0.5 --window 5 [COMMAND]
+
+# Specify a list of nodes for the subcommand
+hytop -H node01,node02 [COMMAND]
+```
+
+## `hytop gpu`
+
+A lightweight script for live `hy-smi` polling with rolling averages across multiple hosts. It features a modern terminal UI and can be used as a blocking scheduler for GPU jobs.
+
+### Usage
+
+Simple examples:
+
+```bash
+# Local node, all GPUs
+hytop gpu
+
+# Two nodes, 0.5-second interval
+hytop -H node01,node02 -n 0.5 gpu
+
+# Exit with code 0 when all monitored GPUs are available
+hytop gpu --devices 0,1 --wait-idle
+
+# Wait for GPUs to be idle for 30 seconds before exiting
+hytop gpu --devices 0,1 --wait-idle --wait-idle-seconds 30
+
+# Wait at most 300s for availability (exit 124 on timeout)
+hytop gpu --devices 0,1 --wait-idle --timeout 300
+
+# Fine-grained columns (output order follows show-flag order)
+hytop gpu --showtemp --showpower
+hytop gpu --showpower --showtemp
+```
+
+Queue jobs in shared environments:
+
+```bash
+if hytop -H node01,node02 gpu --timeout 300 --wait-idle; then
+  echo "GPUs available, starting workload..."
+  # YOUR COMMAND HERE (e.g., python train.py)
+else
+  echo "Error: GPUs not available in time, aborting pipeline."
+fi
+```
+
+### Exit Codes
+
+Designed to be script-friendly:
+
+* `0`: Availability condition met (GPUs are idle).
+* `124`: Timeout reached before the availability condition was met.
+* `130`: Interrupted by the user (Ctrl+C).
+* `2`: Argument or input error.
+
+### Fine-grained metric flags
+
+`hytop gpu` uses formatted `hy-smi --json` output and supports a subset of `hy-smi` `--show*` flags:
+
+- `--showtemp`: GPU core temperature (`Temp`)
+- `--showpower`: average package power (`AvgPwr`, plus `AvgPwr@window`)
+- `--showsclk`: sclk frequency (`sclk`)
+- `--showmemuse`: VRAM usage (`VRAM%`)
+- `--showuse`: GPU utilization (`GPU%`, plus `GPU%@window`)
+
+If no `--show*` flags are specified, hytop defaults to:
+`--showtemp --showpower --showsclk --showmemuse --showuse`.
+
+## Development
+
+Clone the repo and run `make setup` to create the virtual environment, install all dependencies (including dev), and configure pre-commit hooks:
+
+```bash
+make setup
+```
+
+Common development commands:
+
+```bash
+make format     # Auto-fix and format code (ruff)
+make lint       # Check code style and errors without modifying files
+make test       # Run all unit tests (pytest)
+make bump part=patch  # Bump version (patch/minor/major or X.Y.Z)
+make clean      # Remove build caches and the virtual environment
+```
+
+### Version bump
+
+Version is sourced from `src/hytop/__init__.py` (`__version__`).
+
+```bash
+make bump part=patch          # 0.1.0 -> 0.1.1
+make bump part=minor          # 0.1.1 -> 0.2.0
+make bump part=major          # 0.2.0 -> 1.0.0
+make bump part="set 1.2.3"   # set an explicit version
+```
+
+### Publish
+
+Releases are automatically published to PyPI when pushing a version tag:
+
+```bash
+# Bump version and commit
+make bump part=patch
+git commit -am "Bump version to 0.1.1"
+
+# Tag and push to trigger GitHub Actions release
+git tag hytop-0.1.1
+git push origin hytop-0.1.1
+```
+
+To test building distributions locally:
+
+```bash
+make build
+```

hytop-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hytop"
+dynamic = ["version"]
+description = "Lightweight monitoring toolkit for Hygon DCU clusters"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "alephpiece", email = "wangan.cs@gmail.com" }]
+requires-python = ">=3.10"
+dependencies = ["rich>=14", "typer>=0.23"]
+keywords = ["monitoring", "gpu", "dcu", "hygon", "hytop"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: POSIX :: Linux",
+    "Environment :: Console",
+]
+
+[project.urls]
+Homepage = "https://github.com/alephpiece/hg-misc-tools"
+Repository = "https://github.com/alephpiece/hg-misc-tools"
+Issues = "https://github.com/alephpiece/hg-misc-tools/issues"
+
+[project.scripts]
+hytop = "hytop.main:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.15"]
+
+[tool.hatch.version]
+path = "src/hytop/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hytop"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["tests/__pycache__", ".ruff_cache", ".pytest_cache"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "F",   # pyflakes
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+    "RUF", # ruff-specific
+]

hytop-0.1.0/src/hytop/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"