qv

Why qv

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

• Incompatible transitive dependency constraints that break package resolvers.
• Missing dependencies imported in source files but omitted from pyproject.toml.
• Docker containers pinned to older runtimes while developers work on newer Python releases.
• Silent circular imports that only crash at runtime when specific execution paths trigger.

Instead of parsing hundreds of lines of cryptic resolver logs, qv analyzes your project in milliseconds, isolates the root cause, provides concrete evidence, and outputs copy-paste remediation commands.

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

1 Errors   1 Warnings   48 Checks Passed

┌────────────────── [ERROR] 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 via your preferred package manager (provides the qv binary):

# Using pip
pip install python-qv

# Using uv
uv add python-qv --dev

# Run ephemerally without installing
uvx python-qv scan
# or
pipx run python-qv scan

Quick Start

1. Run a Health Scan

Run qv scan in the root of any Python repository:

qv scan

2. Launch the Interactive TUI Explorer

Navigate findings with keyboard controls, view AST details, and trigger 1-key remediation:

qv inspect
# or shorthand
qv ui

3. Generate a Standalone HTML Report

Export an interactive HTML dashboard with health metrics, filters, and dark/light modes:

qv scan --html report.html

4. Explain Any Rule

Get full context, common causes, and remediation advice for any diagnostic rule code:

qv explain DEP-001

5. Initialize Configuration

Add default configuration rules to pyproject.toml without overwriting existing settings:

qv init

Interactive TUI Explorer

Run qv inspect (or qv ui) for a full terminal dashboard:

┌────────────────────────────────────────────── qv Explorer ──────────────────────────────────────────────┐
│  qv Explorer  |  Project: payment-service  |  Health Score: 65/100                                       │
│  Python: 3.12.7  |  Package Manager: uv  |  Errors: 2  |  Warnings: 1  |  Checks Passed: 48             │
├────────────────────────── Findings (1/3) ──────────────────────────┬──────────────── Details: DEP-001 ──┤
│     Sev   Rule     Title                                           │ [ERROR] DEP-001: Constraint conflict│
│  >  ERR   DEP-001  Dependency constraint conflict                  │ celery requires kombu<5.4.0,>=5.3.0│
│     ERR   DEP-002  Missing dependency: httpx                       │ Location: pyproject.toml           │
│     WARN  IMP-003  Unused / orphan module: legacy_calc.py          │                                    │
│                                                                    │ Suggested Remediation:             │
│                                                                    │   Pin kombu to <5.4.0,>=5.3.0      │
│                                                                    │   $ uv add 'kombu<5.4.0'           │
├────────────────────────────────────────────────────────────────────┴────────────────────────────────────┤
│ [Up/k, Down/j] Navigate  |  [Enter] Expand  |  [f] Apply Fix  |  [t] Tree View  |  [q] Quit             │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘

• Up / k & Down / j: Navigate findings list.
• f: Apply automated remediation for selected finding.
• t: Toggle between Findings view and live Dependency Tree.
• Enter: Expand and focus finding details panel.
• q: Exit dashboard.

Rule Categories & Capabilities

qv features over 80 built-in rules across general and framework-specific analyzers:

Refer to the complete Rules Catalog for full descriptions and remediation guides.

CLI Commands & Usage

1. Diagnostic & Health Scanning (qv scan)

Perform comprehensive health scans across dependencies, runtime environment, imports, and framework code.

Standard Project Scan

# Scan current directory
qv scan

# Scan a specific directory or microservice
qv scan ./services/payment

Terminal Output (Healthy Project):

qv
Project: python-qv
Python:  3.12.7
Package Manager: uv

0 Errors   0 Warnings   65 Checks Passed

Everything looks healthy. No diagnostic issues found.
Health Score: 100/100

Terminal Output (Project with Findings):

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

2 Errors   1 Warnings   48 Checks Passed

┌────────────────── [ERROR] 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'                                             │
└──────────────────────────────────────────────────────────────────────────────┘

┌────────────────── [ERROR] DEP-002 Missing dependency declaration ───────────┐
│ Package 'httpx' is imported in src/client.py but is not in pyproject.toml.   │
│                                                                              │
│ Suggested fix:                                                               │
│   $ uv add httpx                                                             │
└──────────────────────────────────────────────────────────────────────────────┘

┌────────────────── [WARN] DEP-002 Undeclared transitive dependency: kombu ────┐
│ Module 'kombu' is imported in src/tasks.py:3 and provided transitively        │
│ by 'celery', but is not declared directly in project dependencies.           │
│                                                                              │
│ Evidence:                                                                    │
│   - Import statement: `import kombu` in src/tasks.py:3                       │
│   - 'kombu' is currently installed as a transitive dependency via 'celery',  │
│     but is not declared directly.                                            │
│                                                                              │
│ Suggested fix:                                                               │
│   Add 'kombu' directly to project dependencies in pyproject.toml.            │
│   $ uv add kombu                                                             │
└──────────────────────────────────────────────────────────────────────────────┘

┌────────────────── [WARN] IMP-003 Unused / orphan local module ──────────────┐
│ File 'src/utils/legacy_calc.py' is never imported by any project module.     │
│                                                                              │
│ Suggested fix:                                                               │
│   Review if this module is obsolete and can be safely deleted.              │
└──────────────────────────────────────────────────────────────────────────────┘

Health Score: 60/100

Strict Mode & Severity Filtering

# Fail with exit code 1 if any warnings or errors exist
qv scan --strict

# Filter by minimum severity level (error, warning, info)
qv scan --severity error

# Shorthand flags
qv scan -E            # --errors-only: display errors only
qv scan -W            # --hide-warnings: hide warning diagnostics

Interactive HTML Dashboard Export

qv scan --html report.html

Terminal Output:

HTML report successfully written to report.html

qv
Project: python-qv
Python:  3.12.7
Package Manager: uv

0 Errors   0 Warnings   65 Checks Passed
Health Score: 100/100

JSON and SARIF Export (CI / Code Scanning)

# Output SARIF format for GitHub Security Code Scanning tab
qv scan --sarif -o results.sarif

# Output machine-readable JSON for custom pipelines
qv scan --json -o findings.json

# Emit GitHub Actions workflow command annotations (::error:: and ::warning::)
qv scan --ci --github-annotations

Airgapped / Offline Mode

# Disable remote network queries (e.g. vulnerability feeds and PyPI index checks)
qv scan --offline

2. Interactive Terminal Dashboard (qv inspect / qv ui)

Launch a full-screen interactive TUI to inspect findings, view location traces, inspect circular import trees, and trigger fixes interactively.

# Inspect current repository
qv inspect

# Shorthand alias
qv ui

# Inspect target project in offline mode
qv inspect ./services/backend --offline

3. Automated Safe Remediation (qv fix)

Safely and automatically apply deterministic configuration and code fixes.

Dry-Run Mode

Preview proposed file modifications and shell commands without writing changes to disk:

qv fix --dry-run

Terminal Output:

Found 2 actionable fix(es) (2 safe):

Proposed Fixes
┌─────────┬────────────────┬───────────────────────────────────────────────────┬──────────────┐
│ Rule    │ Target         │ Description                                       │ Type         │
├─────────┼────────────────┼───────────────────────────────────────────────────┼──────────────┤
│ DEP-002 │ pyproject.toml │ Add missing dependency 'httpx' to pyproject.toml  │ config_patch │
│ DEP-003 │ pyproject.toml │ Remove unused dependency 'pyyaml'                 │ config_patch │
└─────────┴────────────────┴───────────────────────────────────────────────────┴──────────────┘

Dry-run mode enabled. No changes written to disk.

Applying Fixes

# Apply all safe fixes without interactive confirmation prompts
qv fix -y

# Fix a specific rule only
qv fix --rule DEP-002 -y

# Apply fixes and execute package manager sync commands (e.g. uv sync / poetry install)
qv fix -y --sync

Terminal Output:

Found 1 actionable fix(es) (1 safe):

Successfully applied 1 fix(es):
  + Add missing dependency 'httpx' to pyproject.toml

4. Dependency & Import Architecture Visualizer (qv tree / qv graph)

Render structured visual trees of package dependencies and internal source module import architecture.

Full Hierarchy Overview

qv tree

Terminal Output:

Dependency Hierarchy
└── fastapi (0.115.0)
    ├── pydantic (2.9.2)
    │   └── pydantic-core (2.23.4)
    ├── starlette (0.38.6)
    │   └── anyio (4.6.0)
    └── typing-extensions (4.12.2)

Internal Module Import Architecture
└── app.main
    ├── app.api.routes
    │   └── app.core.config
    └── app.db.session
        └── app.models.user [CYCLE DETECTED]

Targeted Tree Views

# Show internal module imports and circular cycles only
qv tree --imports
qv tree -i

# Show direct and transitive package dependencies up to depth 2
qv tree --dependencies --depth 2
qv tree -d -L 2

# Export tree statistics and cycle detection as JSON
qv tree --json

5. Framework-Specific Analyzers (qv framework)

Run dedicated analyzers tailored for popular frameworks.

FastAPI Analyzer (FAP-001 - FAP-038)

qv framework --name fastapi

Terminal Output:

qv (FastAPI Doctor)
Project: my-api
Python:  3.12.7

1 Errors   1 Warnings   32 Checks Passed

┌────────────────── [ERROR] FAP-001 Blocking call in async endpoint ───────────┐
│ File 'src/api/users.py:42'                                                   │
│ Synchronous blocking call 'time.sleep()' inside 'async def get_users()'      │
│ blocks the asyncio event loop and starves concurrent requests.               │
│                                                                              │
│ Suggested fix:                                                               │
│   Use 'await asyncio.sleep()' or run in threadpool via anyio.to_thread.      │
└──────────────────────────────────────────────────────────────────────────────┘

┌────────────────── [WARN] FAP-003 Missing response model ─────────────────────┐
│ Route '@router.get("/items")' in src/api/items.py lacks a response_model.   │
│                                                                              │
│ Suggested fix:                                                               │
│   Add return type annotation: 'async def get_items() -> list[ItemResponse]:' │
└──────────────────────────────────────────────────────────────────────────────┘

SQLAlchemy Analyzer (SQL-001 - SQL-030)

qv framework --name sqlalchemy

Terminal Output:

qv (SQLAlchemy Doctor)
Project: my-api

1 Errors   0 Warnings   28 Checks Passed

┌────────────────── [ERROR] SQL-004 SQL Injection Risk ─────────────────────────┐
│ File 'src/db/repositories/user.py:28'                                        │
│ Raw SQL f-string interpolation detected: text(f"SELECT * FROM users WHERE id={uid}")│
│                                                                              │
│ Suggested fix:                                                               │
│   Use bound query parameters: text("SELECT * FROM users WHERE id = :uid")    │
│   session.execute(stmt, {"uid": uid})                                        │
└──────────────────────────────────────────────────────────────────────────────┘

6. Subsystem-Focused Scans

Run targeted audits on specific components:

# Check dependencies only (conflicts, missing, unused, Python version compat, CVEs)
qv dependency

# Check environment drift only (Python interpreter, Docker base images, CI matrix)
qv environment

# Check AST & imports only (circular import loops, unresolvable modules, orphan files)
qv architecture

7. Rule Explanation & Catalog Lookup (qv explain)

Lookup rule definitions, remediation strategies, and documentation for any diagnostic code:

qv explain FAP-001

Terminal Output:

┌────────────────── FAP-001 - Blocking call in async endpoint ─────────────────┐
│ Category: Framework                                                          │
│ Default Severity: ERROR                                                      │
│                                                                              │
│ Description:                                                                 │
│ Synchronous blocking operations (e.g. time.sleep, requests, subprocess) or    │
│ CPU-bound hashing called inside an async def FastAPI route handler block the │
│ asyncio event loop.                                                          │
│                                                                              │
│ Remediation Recommendation:                                                  │
│ Use non-blocking async alternatives (e.g. asyncio.sleep, httpx.AsyncClient)  │
│ or run blocking/CPU calls in worker threads via anyio.to_thread.run_sync.    │
│                                                                              │
│ Documentation:                                                               │
│ https://github.com/inzamol/qv/blob/main/docs/rules.md#fap-001                │
└──────────────────────────────────────────────────────────────────────────────┘

8. Project Initialization (qv init)

Initialize or append default [tool.qv] settings to pyproject.toml without modifying other configuration tables:

qv init

9. Version & Info (qv version)

qv version

Configuration

Configure qv directly in pyproject.toml to customize severities, ignore rules, or disable specific checks:

[tool.qv]
# Global scan settings
offline = false          # Set true to disable remote CVE/PyPI network queries
hide_warnings = false    # Set true to suppress warning-level diagnostics
errors_only = false      # Set true to report only blocking errors
min_severity = "warning" # Minimum threshold: "error", "warning", or "info"

# Method 1: Turn off specific rules or override severity ("off", "error", "warning", "info")
[tool.qv.rules]
DEP-002 = "off"          # Disable missing/transitive dependency check
IMP-003 = "off"          # Disable orphan module check
DEP-001 = "error"        # Treat dependency conflicts as blocking errors
ENV-002 = "info"         # Demote Docker runtime drift to informational notice

# Method 2: Ignore list for rules
[tool.qv.ignore]
rules = [
    "DEP-004",           # Ignore Python version compatibility mismatch
    "FAP-031",           # Ignore typing.Annotated styling rule
]

# Exclude directories and files from scanning
[tool.qv.paths]
exclude = [
    ".venv",
    "build",
    "dist",
    "legacy_scripts",
    "tests/fixtures",
]

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

Learn more in the Configuration Guide.

CI/CD Integration

Official GitHub Action

Integrate qv directly into .github/workflows/ci.yml:

name: Health & Dependency Scan

on: [push, pull_request]

jobs:
  qv:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run qv Health Scan
        uses: inzamol/qv@v1
        with:
          strict: true
          html_report: report.html
          sarif_report: qv.sarif
          github_annotations: true

GitHub Actions (Manual setup with SARIF code scanning)

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 with PR annotations
      - name: Run qv
        run: uv run qv scan --ci --github-annotations

      # 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()

Pre-commit Hook Integration

Add qv to .pre-commit-config.yaml to detect dependency drift and circular imports prior to commits:

repos:
  - repo: https://github.com/inzamol/qv
    rev: v0.1.0
    hooks:
      - id: qv-scan
        args: [--strict, --offline]

See full details in CI/CD & Pre-commit Integration.

Design Principles

• Diagnose first. Explain second. Fix safely.
• Deterministic and safe: Auto-remediations offer exact diffs and non-destructive configuration updates.
• Local-first and fast: Full AST parsing, dependency graph resolution, and checks complete in under a second.
• Package-manager agnostic: Works with uv, Poetry, pip, PDM, and Pipenv.

Documentation

Full documentation is available at inzamol.github.io/qv.

• Getting Started Guide
• CLI Reference
• Diagnostic Rules Catalog
• Configuration Guide
• CI/CD & SARIF Integration
• Contributing Guidelines

License

Distributed under the MIT License.