CQ006: DeadCodeCheck

Overview

Property Value
ID CQ006
Name DeadCodeCheck
Group code-quality
Severity NOTE

Description

Detects unused code using vulture.

Dead code creates problems:

  • Increases maintenance burden
  • Confuses developers
  • May contain security vulnerabilities
  • Bloats package size

What it checks

The check runs vulture on the package source and:

  • PASSED: No unused code detected
  • FAILED: Unused code found (lists items)
  • NOT_APPLICABLE: vulture is not installed

Vulture detects:

  • Unused functions and methods
  • Unused classes
  • Unused imports
  • Unused variables
  • Unreachable code

How to fix

Install vulture

pip install vulture
# or
uv add --dev vulture

Run vulture

vulture src/my_package
# With minimum confidence
vulture src/my_package --min-confidence 80

Remove unused code

Delete code that vulture identifies as unused:

# Before
def old_function():  # Unused
    pass

def used_function():
    return "used"

# After
def used_function():
    return "used"

Handle false positives

Some code is used dynamically. Create a whitelist file:

# Create whitelist.py
vulture src/my_package --make-whitelist > whitelist.py

Edit whitelist.py to keep only legitimate exceptions:

# whitelist.py
_.dynamic_method  # Used via getattr
_.CONSTANT_FOR_EXPORT  # Part of public API

Run with whitelist:

vulture src/my_package whitelist.py

Configure vulture

Add to pyproject.toml:

[tool.vulture]
exclude = ["tests/", "docs/"]
ignore_decorators = ["@app.route", "@pytest.fixture"]
ignore_names = ["visit_*", "test_*"]
make_whitelist = false
min_confidence = 80
paths = ["src/my_package"]
sort_by_size = true

Common false positives

Framework callbacks:

# Flask/FastAPI routes - add to ignore_decorators
@app.route("/api")
def api_endpoint():  # Appears unused but called by framework
    ...

Test fixtures:

# pytest fixtures - add "test_*" and fixtures to ignore
@pytest.fixture
def client():  # Used by pytest
    ...

Public API:

# Exported in __all__ - whitelist these
__all__ = ["PublicClass", "public_function"]

Plugin entry points:

# Entry points in pyproject.toml - whitelist these
[project.entry-points."console_scripts"]
my-cli = "my_package.cli:main"

Why NOTE severity?

This check is a NOTE because:

  • False positives are common with dynamic code
  • Some “unused” code is intentionally kept
  • Requires careful review before deletion

Configuration

Skip this check

[tool.pycmdcheck]
skip = ["CQ006"]

CLI

pycmdcheck --skip CQ006