CA Django Linters Skill

This skill runs code formatters and linters on Consumer Affairs repositories to ensure code quality and style compliance before commits.

When to Use This Skill

AUTOMATIC ACTIVATION TRIGGERS - Activate this skill immediately when:

• ✅ You've finished writing or modifying ANY Python code in a CA repository
• ✅ Tests have just passed after using the ca-django-tests skill
• ✅ You're about to tell the user that implementation is ready/complete/done
• ✅ User explicitly asks to run linters, format code, or check code style
• ✅ User mentions "ruff", "linting", "formatting", "code quality", "style compliance"
• ✅ Before preparing commits or telling user to commit code

CRITICAL WORKFLOW RULE:

🚨 NEVER tell the user "implementation is complete" or "work is done" UNTIL you have:

1. Run both ruff commands (format + check --fix)
2. Fixed all linting errors
3. Verified code is clean and formatted

This skill should ALWAYS run automatically after code changes and BEFORE declaring work complete.

IMPORTANT: When to Activate

CRITICAL: This skill should run AFTER:

1. ✅ Code implementation is complete
2. ✅ Tests have been written and are passing
3. ✅ You're ready to tell the user the work is done

DO NOT tell the user implementation is complete until:

• ✅ Both ruff commands have been run successfully
• ✅ All linting errors have been fixed
• ✅ Code is clean and ready for commit

Linting Commands

Run these two commands in order:

1. Format Code with Ruff

ca exec ruff format --config pyproject.toml .

This command:

• Automatically formats Python code according to project standards
• Fixes spacing, indentation, and line length issues
• Updates files in place

2. Check and Fix Linting Issues

ca exec ruff check --fix --config pyproject.toml .

This command:

• Checks for code quality issues
• Automatically fixes issues when possible (with --fix flag)
• Reports issues that need manual fixing

Running Linters

Priority Order for Running Linters

1. First Try: ca exec (PREFERRED)

ca exec ruff format --config pyproject.toml .
ca exec ruff check --fix --config pyproject.toml .

This is the preferred method - it uses containers that are already running.

2. If ca exec fails: ca bash then run commands

ca bash
# Inside container:
ruff format --config pyproject.toml .
ruff check --fix --config pyproject.toml .

Use this if ca exec doesn't work for some reason.

IMPORTANT: Container Usage

• DO NOT use docker compose run - this starts a separate container
• DO USE the ca script - it uses already running containers
• The containers should already be running before executing linters

Handling Linting Errors

Auto-fixable Errors

Many errors are automatically fixed by ruff:

• Import sorting issues
• Unused imports
• Whitespace issues
• Simple style violations

After running ruff check --fix, these will be corrected automatically.

Manual Fixes Required

Some errors require manual intervention:

Common Issues and Fixes

1. Undefined names / unused variables

   # Before
   def my_function(arg1, arg2):
       return arg1  # arg2 is unused
   
   # After
   def my_function(arg1, arg2):
       _ = arg2  # Explicitly mark as unused
       return arg1
   

2. Line too long

   # Before
   result = some_function(very_long_argument_1, very_long_argument_2, very_long_argument_3)
   
   # After
   result = some_function(
       very_long_argument_1,
       very_long_argument_2,
       very_long_argument_3
   )
   

3. Missing docstrings

   # Before
   def complex_function(data):
       return process(data)
   
   # After
   def complex_function(data):
       """Process data and return result."""
       return process(data)
   

4. Complexity issues (too many branches)

   • Refactor complex functions into smaller ones
   • Extract logic into helper functions
   • Simplify conditional statements

Workflow for Fixing Errors

1. Run both linting commands
2. Review the output - note all errors and warnings
3. Fix errors one by one:
   • Start with files you recently modified
   • Fix auto-fixable issues first (run with --fix)
   • Then address issues requiring manual fixes
4. Re-run linters to verify all issues are resolved
5. Repeat until both commands pass with no errors

Complete Workflow Example

When user asks to "implement a new authentication feature":

1. Implement the feature - write the code

2. Write tests - use the ca-django-tests skill

3. Run tests - ensure they pass with ca magictest

4. Run linters - use this skill:

   ca exec ruff format --config pyproject.toml .
   ca exec ruff check --fix --config pyproject.toml .
   

5. Fix any linting errors that require manual intervention

6. Re-run linters to confirm all issues are resolved

7. Verify tests still pass after code formatting changes

8. Tell the user the implementation is complete and ready

Success Criteria

Before telling the user work is complete:

• ✅ Both ruff commands run without errors
• ✅ No linting warnings remain
• ✅ Code is properly formatted
• ✅ Tests still pass after formatting
• ✅ Code is ready for commit and CI

Common Patterns in CA Repos

Ignoring Specific Rules

Sometimes you need to ignore a specific rule for a line:

# noqa: E501 - ignore line too long
very_long_line_that_cannot_be_broken = "some value"  # noqa: E501

Configuration Files

The pyproject.toml contains ruff configuration:

• Rule selections
• Line length limits
• Import sorting settings
• File excludes

Do not modify these without discussing with the team.

Error Examples and Solutions

Example 1: Import Sorting

Error: Imports are incorrectly sorted

Solution: Run ruff check --fix - it will auto-fix import order

Example 2: Unused Import

Error: `UserModel` imported but unused

Solution: Remove the import or use it in the code

Example 3: Line Too Long

Error: Line too long (120 > 88 characters)

Solution: Break the line into multiple lines

Example 4: Missing Docstring

Error: Missing docstring in public function

Solution: Add a docstring explaining what the function does

Remember

✅ Always run linters before telling user work is complete ✅ Run both ruff format and ruff check --fix ✅ Fix all errors before finishing ✅ Use ca exec for running linters ✅ Verify tests still pass after formatting ✅ Clean code = ready for commit ✅ Don't modify pyproject.toml without discussion ✅ Fix errors in files you modified first