CQ014: ConsistentImports

Overview

Property Value
ID CQ014
Name ConsistentImports
Group code-quality
Severity NOTE

Description

Ensures import style consistency across the package by detecting files that deviate from the majority import style.

Consistent import styles improve code readability and maintainability:

  • Predictability: Developers know where to look for imports
  • Merge conflicts: Consistent style reduces unnecessary diffs
  • Code review: Easier to spot unusual patterns
  • Tooling: Consistent style works better with import sorters

What it checks

The check analyzes all Python files in the package (excluding test files, hidden directories, and __pycache__) and detects:

  1. Import style deviation: Files that use a different import style than the package majority
  2. Mixed absolute/relative imports: Files that significantly mix both styles

Import styles detected

  • import x style: import os, import json
  • from x import y style: from os import path, from json import loads
  • Absolute imports: from mypackage.utils import helper
  • Relative imports: from .utils import helper, from ..core import base

Result states

  • PASSED: Import styles are consistent across the package
  • FAILED: Files deviate from the majority import style
  • NOT_APPLICABLE: Package directory not found or no imports found
# If most of your package uses from-import style:
from os import path
from json import loads

# This file would be flagged for using import style:
import os
import json

How to fix

Standardize on one import style

Choose either import x or from x import y and use it consistently:

# Consistent from-import style (recommended for specific imports)
from pathlib import Path
from collections import defaultdict
from typing import Optional, List

# Consistent import style (recommended for modules used extensively)
import os
import sys
import json

Use absolute imports within package

# Preferred - absolute imports are clearer
from mypackage.utils import helper
from mypackage.core import base

# Avoid mixing with relative imports in the same file
from .utils import helper  # Don't mix with absolute imports above

If you prefer relative imports, use them consistently

# Consistent relative imports within package
from . import utils
from .core import base
from ..common import helpers

Use isort to enforce consistency

# Install isort
pip install isort

# Format all files
isort .

# Check without modifying
isort --check-only --diff .

Configure isort in pyproject.toml:

[tool.isort]
profile = "black"
known_first_party = ["mypackage"]
force_single_line = false
combine_as_imports = true

Use ruff for import sorting

# Check and fix imports with ruff
ruff check --select I --fix .

Configure ruff in pyproject.toml:

[tool.ruff.lint]
select = ["I"]  # Enable isort rules

[tool.ruff.lint.isort]
known-first-party = ["mypackage"]

Configuration

Adjust deviation threshold

The default allows 30% deviation from the majority style:

[tool.pycmdcheck.checks.CQ014]
deviation_threshold = 0.3  # 30% deviation allowed

Lower values are stricter:

[tool.pycmdcheck.checks.CQ014]
deviation_threshold = 0.1  # Only 10% deviation allowed

Skip this check

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

CLI

pycmdcheck --skip CQ014

Best practices

Group imports consistently

# Standard library imports
import os
import sys
from pathlib import Path

# Third-party imports
import requests
from pydantic import BaseModel

# Local imports
from mypackage.utils import helper
from mypackage.core import base

Avoid wildcard imports

# Bad - pollutes namespace, unclear dependencies
from os import *

# Good - explicit imports
from os import path, getcwd, environ

Use type checking imports properly

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    # These imports only happen during type checking
    from mypackage.heavy_module import ExpensiveClass

Why NOTE severity?

This check is a NOTE because:

  • Import style is largely a matter of team preference
  • Existing codebases may have evolved organically
  • The check is heuristic-based and may flag intentional style choices

However, consistency improves:

  • Code readability
  • Merge conflict reduction
  • Automated tooling effectiveness

References