python-code-quality 0.1.7

Python Code Quality Analysis Tool - feed the results from 11 CQ tools straight into an LLM. Minimal tokens.

CQ - Python Code Quality Analysis Tool

Feed the results from 11+ code quality tools to an LLM. Minimal tokens.

The primary workflow is:

# get the single most critical defect as markdown
cq check . -o llm

Outputs the top error from the first priority tool where the score < warning_threshold,. The code context is expanded if available.

`data/problems/travelling_salesman/ts_bad.py:21` — **F841**: Local variable `unused_variable` is assigned to but never used

18:     min_dist = float("inf")
19:     nearest_city = None
20:     for city in cities:
21:         unused_variable = 67
22:         dist = calc_dist(current_city, city)
23:         if dist < min_dist:
24:             min_dist = dist
25:             nearest_city = city

Please fix only this issue. After fixing, run `cq check . -o llm` to verify.

Feed to an LLM with edit tools and repeat until there are no issues, e.g.

cq check . -o llm | claude -p "fix this"

Install

# install the `cq` command line tool from PyPi
uv tool install python-code-quality

# or, clone it then install 
git pull https://github.com/rhiza-fr/py-cq.git
cd py-cq
uv tool install .

Tools

These tools are run in parallel:

Priority	Tool	Measures
1	compileall	Syntax errors
2	bandit	Security vulnerabilities
3	ruff	Lint / style
4	ty	Type errors
5	pytest	Test pass rate
6	coverage	Test coverage
7	radon cc	Cyclomatic complexity
8	radon mi	Maintainability index
9	radon hal	Halstead volume / bug estimate
10	vulture	Dead code
11	interrogate	Docstring coverage

Diskcache is used to cache tool output for lightning fast re-runs. Sane defaults: <100 Mb, <5 days, No pickle

Usage

# LLM workflow: get the top defect as markdown (primary use case)
cq check -o llm

# Rich table with all metrics
cq check .

# Numeric score only — useful in CI or scripts
cq check . -o score

# Full JSON output, including raw test results
cq check . -o json

# Explicit path
cq check path/to/project/
cq check path/to/file.py

# Run sequentially if you like things slow
cq check . --workers 1

# Clear cached results before running (rarely needed)
cq check . --clear-cache

# Show effective tool configuration (thresholds, enabled/disabled status)
cq config
cq config path/to/project/

Table output

> cq check .

┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ Tool             ┃     Time ┃                    Metric ┃ Score   ┃ Status   ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
│ compile          │    0.42s │                   compile │ 1.000   │ OK       │
│ bandit           │    0.56s │                  security │ 1.000   │ OK       │
│ ruff             │    0.17s │                      lint │ 1.000   │ OK       │
│ ty               │    0.33s │                type_check │ 1.000   │ OK       │
│ pytest           │    0.91s │                     tests │ 1.000   │ OK       │
│ coverage         │    1.26s │                  coverage │ 0.910   │ OK       │
│ radon cc         │    0.32s │                simplicity │ 0.982   │ OK       │
│ radon mi         │    0.38s │           maintainability │ 0.869   │ OK       │
│ radon hal        │    0.30s │             file_bug_free │ 0.928   │ OK       │
│ radon hal        │          │            file_smallness │ 0.851   │ OK       │
│ radon hal        │          │        functions_bug_free │ 0.913   │ OK       │
│ radon hal        │          │       functions_smallness │ 0.724   │ OK       │
│ vulture          │    0.32s │                 dead_code │ 1.000   │ OK       │
│ interrogate      │    0.36s │              doc_coverage │ 1.000   │ OK       │
│                  │          │                     Score │ 0.965   │          │
└──────────────────┴──────────┴───────────────────────────┴─────────┴──────────┘

Single score output

> cq check . -o score

0.9662730667181059 # this is designed to approach but not reach 1.0

Json output

> cq check . -o json

{
  "metrics": [
    {
      "metrics": {
        "compile": 1.0
      },
      "details": {},
      "raw": {
        "tool_name": "compile",
        "command": ".venv\\Scripts\\python.exe -m compileall -r 10 -j 8 . -x .*venv",
        "stdout": "Compiling './src/project/file.py'...",
        "stderr": "",
        "return_code": 0,
        "timestamp": "2026-02-19 05:03:11"
      },
      "duration_s": 0.08294440002646297
    },
    {
      "metrics": {
        "security": 1.0
      }
      // many more lines ...
    }
]}

Configuration

Add a [tool.cq] section to your project's pyproject.toml:

[tool.cq]
# Skip tools that are slow or not relevant to your project
disable = ["coverage", "interrogate"]

# Override warning/error thresholds per tool
[tool.cq.thresholds.coverage]
warning = 0.9
error = 0.7

Tool IDs match the keys in config/tools.yaml: compilation, bandit, ruff, ty, pytest, coverage, complexity, maintainability, halstead, vulture, interrogate.

Default config

tools:

  compilation:
    name: "compile"
    command: "{python} -m compileall -r 10 -j 8 {context_path} -x .*venv"
    parser: "CompileParser"
    priority: 1
    warning_threshold: 0.9999
    error_threshold: 0.9999

  bandit:
    name: "bandit"
    command: "{python} -m bandit -r {context_path} -f json -q -s B101 --severity-level medium --exclude {input_path_posix}/.venv,{input_path_posix}/tests"
    parser: "BanditParser"
    priority: 2
    warning_threshold: 0.9999
    error_threshold: 0.8

  ruff:
    name: "ruff"
    command: "{python} -m ruff check --output-format concise --no-cache {context_path}"
    parser: "RuffParser"
    priority: 3
    warning_threshold: 0.9999
    error_threshold: 0.9

  ty:
    name: "ty"
    command: "{python} -m ty check --output-format concise --color never {context_path}"
    parser: "TyParser"
    priority: 4
    warning_threshold: 0.9999
    error_threshold: 0.8
    run_in_target_env: true
    extra_deps:
      - ty

  pytest:
    name: "pytest"
    command: "{python} -m pytest -v {context_path}"
    parser: "PytestParser"
    priority: 5
    warning_threshold: 0.7
    error_threshold: 0.5
    run_in_target_env: true

  coverage:
    name: "coverage"
    command: "{python} -m coverage run -m pytest {context_path} && {python} -m coverage report"
    parser: "CoverageParser"
    priority: 6
    warning_threshold: 0.9
    error_threshold: 0.5
    run_in_target_env: true
    extra_deps:
      - coverage
      - pytest

  complexity:
    name: "radon cc"
    command: "{python} -m radon cc --json {context_path}"
    parser: "ComplexityParser"
    priority: 7
    warning_threshold: 0.6
    error_threshold: 0.4

  maintainability:
    name: "radon mi"
    command: "{python} -m radon mi -s --json {context_path}"
    parser: "MaintainabilityParser"
    priority: 8
    warning_threshold: 0.6
    error_threshold: 0.4

  halstead:
    name: "radon hal"
    command: "{python} -m radon hal -f --json {context_path}"
    parser: "HalsteadParser"
    priority: 9
    warning_threshold: 0.5
    error_threshold: 0.3

  vulture:
    name: "vulture"
    command: "{python} -m vulture {context_path} --min-confidence 80 --exclude .venv,dist,.*_cache,docs,.git"
    parser: "VultureParser"
    priority: 10
    warning_threshold: 0.9999
    error_threshold: 0.8

  interrogate:
    name: "interrogate"
    command: "{python} -m interrogate {context_path} -v --fail-under 0"
    parser: "InterrogateParser"
    priority: 11
    warning_threshold: 0.8
    error_threshold: 0.3

Respect

Many thanks to all the wonderful maintainers of :

• compileall
• bandit
• ruff
• ty
• pytest
• coverage.py
• radon
• vulture
• interrogate
• diskcache
• typer