05. Code Formatting

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

🎨 Formatting Tool Chain

Primary Tools

Tool	Purpose	Version	Configuration
ufmt	Unified formatting driver	2.9.0	pyproject.toml
ruff-api	Code formatting	0.2.0	pyproject.toml
usort	Import sorting	1.1.0	pyproject.toml
Ruff	Linting and safe fixes	0.16.0	pyproject.toml

Tool Execution Order

graph LR
    A[Source Code] --> B[ufmt]
    B --> C[usort]
    C --> D[ruff-api formatter]
    D --> E[ruff check]
    E --> F[Formatted and linted code]

    C -.->|Import sorting| C1[Alphabetical imports]
    D -.->|Formatting| D1[Code structure]
    E -.->|Linting| E1[Style violations]

Loading

Why this order?

1. ufmt - Runs usort, then the ruff-api formatter
2. ruff - Checks lint rules separately and applies safe fixes when requested

📦 Installation

Quick Setup (Recommended)

# Install all development dependencies
make install-dev

Manual Installation

# Install tritonparse and its pinned development tools
pip install -e ".[dev]"

🚀 Usage Commands

Essential Commands

# Fix all formatting issues
make format

# Fix safe lint issues
make lint

# Check formatting without fixing
make format-check

# Check all configured lint rules without fixing
make lint-check

⚙️ Configuration

Configuration Summary

Tool	Key Settings	Purpose
ruff-api	Line length: 88	PEP 8 compliant formatting
usort	First-party detection: off	Alphabetical import sorting
Ruff	Explicit E4, E7, E9, and F rules	Stable, fast linting

📄 Full Configuration Files

pyproject.toml:

[tool.ufmt]
formatter = "ruff-api"
sorter = "usort"

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

[tool.ruff.lint]
select = ["E4", "E7", "E9", "F"]

[tool.usort]
first_party_detection = false

Makefile:

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

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

# Linting commands
lint:
    python -m tritonparse.tools.format_fix --lint-only --verbose

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

🔧 Developer Workflow

Quick Start

# 1. Make your code changes

# 2. Run formatting
make format

# 3. Verify formatting and lint are clean
make format-check
make lint-check

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

Troubleshooting

Format check fails?

make format          # Fix formatting automatically
make format-check    # Verify formatting
make lint            # Fix safe lint issues automatically
make lint-check      # Verify lint

Need to check specific changes?

ufmt check path/to/file.py
ruff check path/to/file.py

Fix individual files:

ufmt format path/to/file.py
ruff check path/to/file.py --fix

Clear tool caches:

rm -rf .ruff_cache __pycache__
make format

💡 Tip: Run make format, make lint, make format-check, and make lint-check before committing.

🤖 CI Integration

GitHub Actions Workflow

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@v6
    - name: Set up Python 3.14
      uses: actions/setup-python@v6
      with:
        python-version: "3.14"
    - name: Install development dependencies
      run: make install-dev
    - name: Check code formatting
      run: make format-check
    - name: Check linting
      run: make lint-check

CI Process:

1. Install dependencies → make install-dev
2. Check formatting → make format-check
3. Verify linting → make lint-check
4. Block merge if any check fails

🔍 Tool Details

ufmt and ruff-api - Run import sorting and deterministic code formatting as one atomic operation. The ruff-api formatter uses an 88-character line length.

usort - Sorts imports alphabetically within categories: standard library, third-party packages, and local modules. Groups imports with blank lines between categories.

Ruff - Fast linter that checks code style violations, unused imports, syntax errors, and type annotation issues. Auto-fixes safe issues.

Formatting Example

# Before formatting
import triton
import os
import torch
from pathlib import Path
def my_function(x,y,z):
    return x+y+z

# After: ufmt (usort → ruff-api formatter)
import os
from pathlib import Path

import torch
import triton


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

🚨 Common Issues

Issue	Error Message	Quick Fix
Import Order	E402: Module level import not at top of file	Move all imports to file top, before code
Formatting vs linting	Different checks report different issues	Run make format, then make lint
Import Sorting	usort breaks functionality	Use # usort: skip comment for file/import
Line Length	Line exceeds 88 characters	Use parentheses for multi-line breaks

Example Solutions

Import Order:

# Wrong
print("Starting")
import os

# Correct
import os
print("Starting")

Line Length:

# Use parentheses
result = some_function(
    very_long_argument,
    another_argument,
    third_argument
)

# Split strings
message = (
    "Long message that would "
    "exceed line length"
)

Skip Sorting:

# usort: skip
import special_module  # usort: skip

🎯 Best Practices

✅ Do's

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

❌ Don'ts

• 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

🔧 Editor Integration

VS Code: Configure ufmt as the formatter and install the Ruff extension for linting. Enable editor.formatOnSave in settings.

PyCharm: Configure ufmt as an external formatter and enable Ruff inspection.

Vim/Neovim: Configure your formatter integration to run ufmt and use Ruff's language server for linting.

💡 See your editor's plugin documentation for detailed setup instructions.

🌍 Integration with PyTorch Ecosystem

This formatting setup follows PyTorch ecosystem patterns:

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

🆘 Getting Help

For formatting issues:

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

📚 Related Documentation

• Developer Guide - Complete development workflow
• Contributing - Contribution guidelines
• Python API Reference - API documentation
• 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, make lint, make format-check, and make lint-check.