🔍 qv

💡 Why qv?

Python projects rarely fail because of Python syntax. They fail because of ecosystem friction:

• Incompatible transitive dependency constraints that break your resolver.
• Missing dependencies you forgot to add to pyproject.toml.
• Docker containers running Python 3.10 while your team develops on 3.12.
• Silent circular imports that only crash at runtime when certain modules load.

Instead of parsing hundreds of lines of cryptic resolver logs, qv scans your project in milliseconds, pinpoints the root cause, shows the exact evidence, and gives you a copy-paste command to fix it.

🔍 qv
Project: payment-service
Python:  3.12.7
Package Manager: uv

🔴 1 Errors   🟡 1 Warnings   🟢 48 Checks Passed

┌────────────────── 🔴 DEP-001 Dependency constraint conflict ─────────────────┐
│ celery 5.4.0 requires kombu<5.4.0,>=5.3.0, but installed is kombu 5.5.2.     │
│                                                                              │
│ Evidence:                                                                    │
│   • celery declared requirement: kombu<5.4.0,>=5.3.0                         │
│   • Installed kombu version: 5.5.2 in active environment                     │
│                                                                              │
│ Suggested fix:                                                               │
│   Upgrade celery or pin kombu to <5.4.0,>=5.3.0.                             │
│   $ uv add 'kombu<5.4.0,>=5.3.0'                                             │
└──────────────────────────────────────────────────────────────────────────────┘

Health Score: 85/100

📦 Installation

Install python-qv into your virtual environment (provides the qv CLI):

# Using pip
pip install python-qv

# Using uv
uv add python-qv --dev

# Run directly without installing (via uvx or pipx)
uvx python-qv scan
# or
pipx run python-qv scan

🚀 Quick Start

1. Run a Health Scan

Run qv scan inside any Python repository:

qv scan

2. Understand Any Flagged Issue

Need more context on why a rule triggered? Run explain:

qv explain DEP-001

3. Add Project Configuration

To add default configuration to your pyproject.toml:

qv init

🔍 What It Detects

👉 See full explanations and remediation steps in the Rules Catalog.

🛠️ CLI Commands

# Full project diagnostic scan
qv scan

# Scan another folder
qv scan ./services/billing

# Strict mode: fail CI on warnings as well as errors
qv scan --strict

# Output machine-readable formats
qv scan --json
qv scan --sarif -o results.sarif

# Run focused subsystem scans
qv dependency       # Check package constraints & imports
qv environment      # Check Python, Docker & CI version drift
qv architecture     # Check for circular imports & dead paths

# Explain a rule
qv explain DEP-002

# Check installed version
qv version

👉 See detailed options in the CLI Reference.

⚙️ Configuration

Configure qv in your pyproject.toml:

[tool.qv]

# Override severity for any rule (error, warning, info, off)
[tool.qv.rules]
DEP-001 = "error"
DEP-003 = "warning"
ENV-002 = "info"

# Ignore specific rules
[tool.qv.ignore]
rules = ["DEP-004"]

# Exclude directories from scanning
[tool.qv.paths]
exclude = [
    ".venv",
    "build",
    "dist",
    "legacy_scripts",
]

# Set expected target Python version
[tool.qv.runtime]
python = "3.12"

👉 Learn more in the Configuration Guide.

🤖 CI/CD Integration

GitHub Actions (with SARIF code scanning)

Add this step to your GitHub Actions workflow (.github/workflows/ci.yml):

name: Health & Dependency Scan

on: [push, pull_request]

jobs:
  qv:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3

      # Run scan in CI mode
      - name: Run qv
        run: uv run qv scan --ci

      # Optional: Generate SARIF report for GitHub Code Scanning
      - name: Generate SARIF report
        run: uv run qv scan --sarif -o qv.sarif
        if: always()

      - name: Upload SARIF to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: qv.sarif
        if: always()

👉 See full details in CI/CD Integration.

🎯 Design Principles

• Diagnose first. Explain second. Fix safely.
• No destructive auto-mutations: Remediations provide the exact commands/diffs for you to review and apply.
• Local-first & Blazing fast: Zero network calls required; scans complete in under a second.
• Package-manager agnostic: Works out of the box with uv, Poetry, pip, PDM, and Pipenv.

📚 Complete Documentation

• 🚀 Getting Started Guide
• 📖 CLI Reference
• 📋 Diagnostic Rules Catalog
• ⚙️ Configuration Guide
• 🤖 CI/CD & SARIF Integration
• 🤝 Contributing Guidelines

📄 License

Distributed under the MIT License.