hyper2kvm

Building and Testing hyper2kvm

This document explains how to build, test, and develop hyper2kvm using the modern Python toolchain.

Quick Start

# For enterprise users familiar with Make
make help          # Show all available commands
make test          # Run tests
make install       # Install the package

# For Python developers
pip install hatch
hatch run test     # Run tests
hatch run lint     # Run linting
hatch build        # Build package

Build System

hyper2kvm uses a hybrid build system:

This approach provides:

Installation

# Install Hatch
pip install hatch

# Or via pipx (isolated install)
pipx install hatch

# On Fedora/RHEL (future, not yet packaged)
# dnf install python-hatch

Quick Development Setup

# Option 1: Using Make (auto-installs hatch)
make quickstart

# Option 2: Using Hatch directly
pip install hatch
pip install -e .[dev,full]

Testing

Using Make

make test              # Run unit tests
make test-unit         # Unit tests only
make test-integration  # Integration tests only
make test-all          # All tests
make test-cov          # Tests with coverage report
make test-matrix       # Test across Python 3.10, 3.11, 3.12

Using Hatch

hatch run test              # Run unit tests
hatch run test-unit         # Unit tests only
hatch run test-integration  # Integration tests
hatch run test-all          # All tests
hatch run test-cov          # With coverage
hatch run test-cov-all      # Coverage for all tests

Using pytest directly

pytest tests/unit/ -v
pytest tests/unit/ --cov=hyper2kvm --cov-report=html
pytest tests/integration/ -v

Code Quality

Using Make

make lint        # Run ruff + mypy
make fmt         # Auto-format code
make fmt-check   # Check formatting without changes
make security    # Run security scans (bandit + safety)

Using Hatch

hatch run lint              # Linting
hatch run fmt               # Format code
hatch run fmt-check         # Check formatting
hatch run security          # Security scans
hatch run security-audit    # Generate security report

Building

Source and Wheel Distribution

# Using Make
make build

# Using Hatch
hatch build

# Using Python directly
python -m build

Output: dist/hyper2kvm-{version}.tar.gz and dist/hyper2kvm-{version}-py3-none-any.whl

RPM Package (Fedora/RHEL)

# Using Make
make rpm

# Manually
python3 -m build --sdist
rpmbuild -ba hyper2kvm.spec

Publishing

To PyPI

# Using Hatch (recommended)
export HATCH_INDEX_USER=__token__
export HATCH_INDEX_AUTH=pypi-...
hatch publish

# Using Make
make publish

# To TestPyPI first
make publish-test

CI/CD Pipeline

Full CI Check

# Using Make
make ci          # test-cov + lint + security

# Using Hatch
hatch run ci     # Same as above

# Individual checks
make check       # test + lint + security (without coverage)

CI Usage (GitHub Actions)

- name: Run tests
  run: hatch run test

- name: Run linting
  run: hatch run lint

- name: Full CI pipeline
  run: hatch run ci

Development Workflow

1. Setup Development Environment

# Clone repository
git clone https://github.com/ssahani/hyper2kvm.git
cd hyper2kvm

# Install in development mode
make dev-install
# OR
pip install -e .[dev,full]

2. Make Changes

Edit code in hyper2kvm/ directory.

3. Test Changes

# Quick test
make test

# Full check before commit
make check

4. Format Code

make fmt

5. Commit

git add .
git commit -m "Your changes"

Environment Management

Hatch Environments

Hatch manages isolated environments defined in pyproject.toml:

# Show all environments
hatch env show

# Run command in specific environment
hatch -e dev run docs-build

# Remove all environments (clean slate)
hatch env prune

# Create environment
hatch env create

Available Scripts

All scripts are defined in pyproject.toml under [tool.hatch.envs.default.scripts]:

Command Description
test Run unit tests
test-unit Unit tests only
test-integration Integration tests
test-all All tests
test-cov Tests with coverage
test-cov-all Coverage for all tests
lint Ruff + mypy linting
fmt Format code with ruff
fmt-check Check formatting
security Bandit + safety scans
security-audit Generate security JSON report
check test + lint + security
ci test-cov + lint + security

Cleaning

# Clean build artifacts
make clean

# Clean everything (including test data)
make clean-all

# Using Hatch
hatch clean

Documentation

Build Documentation

# Using Make
make docs
make docs-serve  # Serve on http://localhost:8000

# Using Hatch
hatch run docs-build
hatch run docs-serve

# Manually
cd man && make html

Troubleshooting

Hatch Not Found

# Install hatch
pip install hatch

# Or the Makefile will auto-install it
make test

Coverage Report Not Generated

# Make sure you're using test-cov target
make test-cov

# Report will be in htmlcov/index.html
open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux

Import Errors in Tests

# Reinstall in development mode
pip install -e .

# Or
make dev-install

Matrix Testing Fails

# Install all Python versions (using pyenv)
pyenv install 3.10 3.11 3.12
pyenv local 3.10 3.11 3.12

# Run matrix tests
hatch run test:run

Migration from Old Setup

If you’re migrating from the old setup:

# Old way
pytest tests/unit/ -v
ruff check hyper2kvm/
mypy hyper2kvm/

# New way (Make)
make test
make lint

# New way (Hatch)
hatch run test
hatch run lint

References

Summary

Task Make Hatch
Run tests make test hatch run test
Test with coverage make test-cov hatch run test-cov
Lint code make lint hatch run lint
Format code make fmt hatch run fmt
Security scan make security hatch run security
Build package make build hatch build
Install dev mode make dev-install pip install -e .[dev,full]
Clean artifacts make clean hatch clean
Full CI check make ci hatch run ci

Recommendation: Use make for quick commands, use hatch for advanced features and environment management.

This site is open source. Improve this page.