Skip to content

qv Documentation

Diagnose why your Python project is unhealthy — understand the root cause and get safe, actionable fixes.

PyPI Version Python Versions License: MIT

qv is a high-performance, offline-first health analyzer for Python projects. It inspects your project manifests, active virtual environment, source module AST, and packaging metadata in milliseconds to uncover broken dependencies, undeclared packages, circular import loops, and runtime drift across Docker and CI.

1. Overview & Architecture

Unlike generic tools that only inspect a single lockfile or flat requirements list, qv correlates multi-layer diagnostic signals across your entire project ecosystem:

flowchart TD
    subgraph Discovery["1. Discovery & Context Ingestion"]
        A["<b>Project Manifests & Active Environment</b><br/>pyproject.toml • requirements.txt • active virtualenv"]
        B["<b>Source Code AST & Infrastructure</b><br/>Module AST imports • Dockerfile • CI workflows"]
    end

    subgraph Analyzers["2. Subsystem Analyzers"]
        C["<b>Dependencies Analyzer</b><br/>Constraint conflicts, missing & unused packages"]
        D["<b>Environment & Drift Analyzer</b><br/>Python interpreter, Docker base image & CI matrix drift"]
        E["<b>Imports & Architecture Analyzer</b><br/>Circular import cycle detection & unresolvable modules"]
        F["<b>Packaging Analyzer</b><br/>PEP 621 metadata & configuration schema"]
    end

    subgraph Correlator["3. Root Cause Engine & Health Score"]
        G["<b>Correlated Diagnostic Model</b><br/>Evidence mapping, root causes & Health Score (0–100)"]
    end

    subgraph Output["4. Multi-Channel Output & Remediation"]
        H["<b>Interactive Terminal Dashboard</b> (`qv inspect`)"]
        I["<b>Standalone HTML Reports</b> (`qv scan --html`)"]
        J["<b>CI / SARIF & Annotations</b> (`qv scan --sarif`)"]
        K["<b>Automated Safe Fixes</b> (`qv fix -y`)"]
    end

    A --> Analyzers
    B --> Analyzers
    Analyzers --> Correlator
    Correlator --> H
    Correlator --> I
    Correlator --> J
    Correlator --> K

👉 Learn more in the comprehensive Architecture & Internal Design documentation.

2. Install & Usage

Run qv scan directly in any Python project root without configuration or network access:

uv add python-qv --dev
uv run qv scan

pip install python-qv
qv scan

uvx python-qv scan

pipx run python-qv scan

2.1 Live Diagnostic Output

🔍 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

3. Core Feature Pillars

  • Interactive Terminal Dashboard

    Explore findings interactively with keyboard navigation (↑/↓), expand evidence, view live dependency trees (t), and apply fixes (f) in a rich TUI.

    Open TUI Guide

  • Self-Contained HTML Reports

    Generate portable, zero-dependency HTML reports (qv scan --html) with circular health score gauges, real-time search, severity filters, and dark mode.

    Open HTML Report Guide

  • Safe Automated Fixes

    Compute deterministic remediation plans with qv fix --dry-run and safely synchronize manifests and package managers with qv fix --sync -y.

    Open Remediation Guide

  • Dependency & Import Trees

    Visualize direct vs transitive package trees (qv tree -d) and internal module import architecture with circular loops highlighted (qv tree -i).

    Open Tree Visualizer Guide

4. Diagnostic Subsystems

Subsystem Scope & Capabilities Key Rules
Dependencies Constraint conflicts, undeclared imports, unused packages, Python compatibility mismatches DEP-001 through DEP-006
Environment Interpreter version drift, Dockerfile base image mismatches, CI matrix synchronization ENV-001 through ENV-003
Architecture Circular import cycle detection, unresolvable module imports, dead orphan files, deprecated stdlib IMP-001 through IMP-004
Packaging PEP 621 metadata validation, TOML syntax verification, entrypoint checks PKG-001, PKG-002

👉 Browse full rule descriptions and remediation strategies in the Rules Catalog.

5. Feature Comparison

Capability qv pip check deptry pip-audit
Dependency Constraint Conflicts ✅ ✅ ❌ ❌
Undeclared & Unused Dependencies ✅ ❌ ✅ ❌
Circular Import Cycle Detection ✅ ❌ ❌ ❌
Python & Docker/CI Runtime Drift ✅ ❌ ❌ ❌
Interactive Terminal Explorer (TUI) ✅ ❌ ❌ ❌
Standalone Interactive HTML Reports ✅ ❌ ❌ ❌
Automated Safe Remediation (qv fix) ✅ ❌ ❌ ❌
SARIF v2.1.0 & GitHub PR Annotations ✅ ❌ ❌ ❌
Sub-Second Offline Execution ✅ ✅ ✅ ❌ (requires network)

6. Explore Documentation

  • Architecture & Design

    Deep dive into discovery pipelines, immutable models, and analyzer subsystems.

    Explore Architecture

  • Getting Started Guide

    Step-by-step setup, first health scan, and baseline configuration.

    Read Getting Started

  • CLI Commands Reference

    Complete flag reference, exit codes, and output formatting options.

    Explore CLI Reference

  • Diagnostic Rules Catalog

    Exhaustive documentation for every diagnostic rule and remediation plan.

    View Rules Catalog

  • Configuration Guide

    Configure severities, ignore rules, and exclude path patterns in pyproject.toml.

    View Configuration

  • CI/CD & GitHub Actions

    Integrate with GitHub Actions, SARIF code scanning alerts, and workflows.

    View CI Integration

  • Pre-commit Integration

    Enforce clean health scans before commits reach your remote repository.

    View Pre-commit Guide

  • Contributing Guide

    Development environment setup, Tox testing matrix, and authoring new rules.

    Read Contributing