This guide covers the comprehensive code formatting and linting setup for TritonParse, ensuring consistent code quality across all contributions.

graph LR
    A[Source Code] --> B[usort]
    B --> C[ruff check]
    C --> D[black]
    D --> E[Formatted Code]
    
    B -.->|Import sorting| B1[Alphabetical imports]
    C -.->|Linting| C1[Style violations]
    D -.->|Formatting| D1[Code structure]

Why this order?

1. usort - Sorts imports first (affects line numbers)
2. ruff - Lints and auto-fixes issues
3. black - Final formatting pass

# Install all development dependencies
make install-dev

# Install tritonparse in development mode
pip install -e ".[test]"

# Install formatting tools
pip install black usort ruff

# Fix all formatting issues
make format

# Check if code is properly formatted (CI-compatible)
make lint-check

# Check formatting without fixing
make format-check

[tool.black]
line-length = 88
target-version = ["py310"]

[tool.usort]
first_party_detection = false

# Development dependencies
install-dev:
    pip install -e ".[test]"
    pip install black usort ruff

# Formatting commands
format:
    python -m tritonparse.tools.format_fix --verbose

format-check:
    python -m tritonparse.tools.format_fix --check-only --verbose

# Linting commands  
lint-check:
    ruff check --diff .
    black --check --diff .

# 1. Make your code changes
# 2. Run formatting
make format

# 3. Verify everything is clean
make lint-check

# 4. Commit your changes
git add .
git commit -m "Your changes"

If make lint-check fails:

# Run the formatter
make format

# Check if issues are resolved
make lint-check

# If still failing, check the diff
ruff check --diff .
black --check --diff .

The project uses GitHub Actions to automatically check code formatting on every push and pull request. This ensures consistent code quality across all contributions.

# Manual quality check before pushing
make format-check
make lint-check

The CI pipeline includes a format-check job that:

1. Installs dependencies via make install-dev
2. Checks formatting via make format-check
3. Verifies linting via make lint-check
4. Blocks merging if formatting fails

format-check:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Set up Python 3.11
      uses: actions/setup-python@v4
      with:
        python-version: "3.11"
    - name: Install development dependencies
      run: make install-dev
    - name: Check code formatting
      run: make format-check
    - name: Check linting
      run: make lint-check

graph TD
    A[format-check] --> B[test]
    A --> C[Install deps]
    A --> D[Check formatting]
    A --> E[Check linting]
    
    F[test success] --> G[Merge allowed]
    A --> F

Configuration:

• Line length: 88 characters
• Target: Python 3.10+
• Style: Black default (PEP 8 compliant)

What it formats:

• Code structure and spacing
• String quotes (double quotes preferred)
• Line breaks and indentation
• Trailing commas

Example:

# Before
def my_function(x,y,z):
    return x+y+z

# After
def my_function(x, y, z):
    return x + y + z

Configuration:

• First-party detection: Disabled
• Sorting: Alphabetical within categories
• Categories: Standard library, third-party, local

What it sorts:

• Import statements
• From imports
• Import grouping

Example:

# Before
import triton
import os
import torch
from pathlib import Path

# After
import os
from pathlib import Path

import torch
import triton

Configuration:

• Rules: Built-in defaults
• Auto-fix: Enabled for safe fixes
• Purpose: Linting only (no formatting)

What it checks:

• Code style violations
• Unused imports
• Syntax errors
• Type annotation issues

Example:

# Before - Ruff will flag unused import
import os
import sys  # unused

def hello():
    print("Hello")

# After - Ruff auto-fixes
import os

def hello():
    print("Hello")

Error: Module level import not at top of file

Solution: Move imports to the top of the file, before any code:

# Wrong
print("Starting script")
import os

# Correct
import os
print("Starting script")

Error: Black and Ruff suggest different formatting

Solution: Use Black for formatting, Ruff for linting only:

# This is handled automatically by our tools
# But if you see conflicts, run:
make format  # Black will win

Error: usort changes break functionality

Solution:

• Check for circular imports
• Verify conditional imports
• Use # usort: skip for special cases

# Skip sorting for this file
# usort: skip

# Or skip specific imports
import special_module  # usort: skip

Error: Line too long (> 88 characters)

Solutions:

# Use parentheses for line breaks
result = some_function(
    very_long_argument_name,
    another_long_argument,
    third_argument
)

# Split long strings
message = (
    "This is a very long message that would "
    "exceed the line length limit"
)

For persistent issues:

# See what needs to be changed
ruff check --diff .
black --check --diff .

# Fix specific file
black path/to/file.py
usort format path/to/file.py
ruff check path/to/file.py --fix

# Clear formatting tool caches
rm -rf .ruff_cache
rm -rf __pycache__

# Re-run formatting
make format

• Run make format before every commit
• Use make lint-check to verify CI compatibility
• Follow the tool chain order: usort → ruff → black
• Keep line length at 88 characters (Black default)
• Use descriptive commit messages for formatting changes

• Don't bypass formatting checks in CI
• Don't mix formatting with feature changes in commits
• Don't manually format code that tools can handle
• Don't ignore linting errors without good reason
• Don't modify tool configurations without discussion

{
  "python.formatting.provider": "black",
  "python.sortImports.args": ["--profile", "black"],
  "editor.formatOnSave": true,
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true
}

1. Install Black plugin
2. Configure external tool for usort
3. Set code style to match Black
4. Enable Ruff inspection

" Install plugins
Plug 'psf/black', { 'branch': 'stable' }
Plug 'charliermarsh/ruff-lsp'

" Configure auto-formatting
autocmd BufWritePre *.py execute ':Black'

The main formatting script is located at:

• tritonparse/tools/format_fix.py

# Script execution order:
1. run_usort()        # Sort imports
2. run_ruff_check()   # Lint code (fix auto-fixable)
3. run_black()        # Format code structure

# Each tool operates on the entire project (.)

All tools operate on:

• tritonparse/ package directory
• tests/ directory
• Root-level Python files
• Excludes: __pycache__, .git, build artifacts

This formatting setup follows PyTorch ecosystem patterns:

• Black for primary formatting (industry standard)
• usort for import management (Meta/Facebook standard)
• Ruff for fast linting (modern Python tooling)
• 88-character line length (Black default)

• Python: 3.10+
• Black: 24.4.2+
• usort: 1.0.8+
• Ruff: 0.1.0+

For formatting issues:

1. Check this guide first
2. Run make format and make lint-check
3. Review the troubleshooting section
4. Check CI logs for specific errors
5. Ask in GitHub Discussions

• Developer Guide - Complete development workflow
• Contributing - Contribution guidelines
• Installation - Development setup
• GitHub Issues - Report formatting bugs

Note: This formatting setup ensures consistent code quality across all contributions. When in doubt, run make format followed by make lint-check to resolve most issues automatically.