Skip to content

QUALITY_TOOLS.md

Latest commit

 

History

History
179 lines (125 loc) · 3.29 KB

QUALITY_TOOLS.md

File metadata and controls

179 lines (125 loc) · 3.29 KB

Code Quality Tools

This project uses modern Python code quality tools to maintain consistency and catch issues early.

Tools Installed

  1. Black - Opinionated code formatter
  2. Ruff - Fast Python linter (replaces flake8, isort, and more)
  3. mypy - Static type checker

Configuration

All tools are configured in pyproject.toml:

  • Black: 100 character line length, Python 3.13 target
  • Ruff: Comprehensive linting rules including import sorting, code simplification, and bug detection
  • mypy: Type checking with relaxed settings (can be made stricter later)

Available Scripts

Quick Commands

# Auto-fix formatting and linting issues
./fix.sh

# Run all quality checks (no changes)
./check.sh

Individual Tools

# Format code with Black
./format.sh

# Run linter
./lint.sh

# Type check
./typecheck.sh

Development Workflow

Before Committing

Always run the fix script to auto-format and fix linting issues:

./fix.sh

Then verify everything passes:

./check.sh

CI/CD Integration

Add to your CI pipeline:

# Check formatting (fails if not formatted)
uv run black --check backend/

# Check linting
uv run ruff check backend/

# Run type checks
uv run mypy backend/

Ruff Rules Enabled

  • E - pycodestyle errors
  • W - pycodestyle warnings
  • F - pyflakes
  • I - isort (import sorting)
  • B - flake8-bugbear
  • C4 - flake8-comprehensions
  • UP - pyupgrade
  • ARG - flake8-unused-arguments
  • SIM - flake8-simplify

Manual Fixes Required

Some issues require manual intervention:

  1. E402 (Module level import not at top) - Fixed by moving imports to the top
  2. SIM108 (Use ternary operator) - Simplified if-else to ternary
  3. B905 (zip without strict) - Added strict=True to zip calls
  4. Type annotations - mypy will highlight these (optional to fix)

Type Checking Strategy

Type checking is currently set to disallow_untyped_defs = false to allow gradual adoption. To make it stricter:

  1. Edit pyproject.toml:

    [tool.mypy]
disallow_untyped_defs = true

  2. Add type hints to functions:

    def my_function(param: str) -> int:
    return len(param)

  3. Run ./typecheck.sh to verify

Editor Integration

VS Code

Install these extensions:

  • Python (Microsoft)
  • Black Formatter
  • Ruff

Add to .vscode/settings.json:

{
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "python.linting.enabled": true,
  "ruff.enable": true
}

PyCharm

  1. Go to Settings → Tools → Black
  2. Enable "Run Black on save"
  3. Go to Settings → Tools → External Tools
  4. Add Ruff as an external tool

Troubleshooting

Scripts not executable

chmod +x *.sh

Line ending issues (Windows)

sed -i 's/\r$//' *.sh

Tool not found

Ensure dependencies are installed:

uv sync

Dependencies Added

These dev dependencies were added to pyproject.toml:

[dependency-groups]
dev = [
    "black>=26.1.0",
    "mypy>=1.19.1",
    "ruff>=0.14.14",
]

To update them:

uv lock --upgrade