python-mode/doc/MIGRATION_GUIDE.md at develop · python-mode/python-mode · GitHub
Skip to content

MIGRATION_GUIDE.md

Latest commit

 

History

History
310 lines (222 loc) · 8.32 KB

MIGRATION_GUIDE.md

File metadata and controls

310 lines (222 loc) · 8.32 KB

Migration Guide: From Old Linting Tools to Ruff

This guide helps you migrate from the old python-mode linting configuration (using pylint, pyflakes, pycodestyle, etc.) to the new Ruff-based system.

Overview

Python-mode now uses Ruff instead of multiple separate linting tools. Ruff is:

  • 10-100x faster than the old tools
  • Single unified tool replacing pyflakes, pycodestyle, mccabe, pylint, pydocstyle, autopep8
  • Backward compatible - your existing configuration is automatically mapped to Ruff rules

Quick Start

1. Install Ruff

pip install ruff

Verify installation:

ruff --version

2. Your Existing Configuration Still Works!

The good news: You don't need to change anything immediately. Your existing g:pymode_lint_* options are automatically mapped to Ruff rules.

For example:

" Your old configuration still works!
let g:pymode_lint_checkers = ['pyflakes', 'pycodestyle', 'mccabe']
let g:pymode_lint_ignore = ["E501", "W"]

This is automatically converted to equivalent Ruff rules.

3. (Optional) Migrate to Ruff-Specific Options

For better control and performance, you can migrate to Ruff-specific options:

" Enable Ruff linting and formatting
let g:pymode_ruff_enabled = 1
let g:pymode_ruff_format_enabled = 1

" Ruff-specific ignore rules (takes precedence over g:pymode_lint_ignore)
let g:pymode_ruff_ignore = ["E501", "W"]

" Ruff-specific select rules (takes precedence over g:pymode_lint_select)
let g:pymode_ruff_select = []

" Optional: Specify Ruff config file
let g:pymode_ruff_config_file = ""

Configuration Mapping

Legacy Options → Ruff Rules

Old Option Ruff Equivalent Notes
g:pymode_lint_checkers = ['pyflakes'] Ruff F rules F401, F402, F403, etc.
g:pymode_lint_checkers = ['pycodestyle'] Ruff E/W rules E501, W292, etc.
g:pymode_lint_checkers = ['mccabe'] Ruff C90 rules C901 (complexity)
g:pymode_lint_checkers = ['pylint'] Ruff PLE/PLR/PLW rules PLE0001, PLR0913, etc.
g:pymode_lint_checkers = ['pep257'] Ruff D rules D100, D101, etc.
g:pymode_lint_ignore = ["E501"] Ruff ignore E501 Same rule code
g:pymode_lint_select = ["W0011"] Ruff select W0011 Same rule code

Note: Rule codes are mostly compatible. See RUFF_CONFIGURATION_MAPPING.md for detailed mappings.

Using Ruff Configuration Files

Ruff supports configuration via pyproject.toml or ruff.toml:

pyproject.toml:

[tool.ruff]
line-length = 88
select = ["E", "F", "W"]
ignore = ["E501"]

[tool.ruff.lint]
select = ["E", "F", "W"]
ignore = ["E501"]

ruff.toml:

line-length = 88
select = ["E", "F", "W"]
ignore = ["E501"]

Python-mode will automatically use these files if they exist in your project root.

Configuration Precedence

Python-mode now supports flexible configuration precedence via g:pymode_ruff_config_mode:

Default Behavior ("local_override"):

  • If your project has a local ruff.toml or pyproject.toml with [tool.ruff] section, it will be used
  • If no local config exists, python-mode settings serve as fallback
  • This ensures project-specific configs are respected while providing defaults

Using Only Local Config ("local"):

let g:pymode_ruff_config_mode = "local"

Use this when you want python-mode to completely respect your project's Ruff configuration and ignore all python-mode settings.

Using Only Global Config ("global"):

let g:pymode_ruff_config_mode = "global"

Use this to restore the previous behavior where python-mode settings always override local configs. Local config files will be ignored.

Note: The default "local_override" mode is recommended for most users as it respects project standards while providing sensible defaults.

Step-by-Step Migration

Step 1: Verify Ruff Installation

pip install ruff
ruff --version

Step 2: Test Your Current Setup

Your existing configuration should work immediately. Try:

:PymodeLint        " Should work with Ruff
:PymodeLintAuto    " Should format with Ruff

Step 3: (Optional) Create Ruff Config File

Create pyproject.toml or ruff.toml in your project root:

[tool.ruff]
line-length = 88
select = ["E", "F", "W"]
ignore = ["E501"]

Step 4: (Optional) Migrate to Ruff-Specific Options

Update your .vimrc:

" Old way (still works)
let g:pymode_lint_checkers = ['pyflakes', 'pycodestyle']
let g:pymode_lint_ignore = ["E501"]

" New way (recommended)
let g:pymode_ruff_enabled = 1
let g:pymode_ruff_format_enabled = 1
let g:pymode_ruff_ignore = ["E501"]

Common Scenarios

Scenario 1: Using pyflakes + pycodestyle

Before:

let g:pymode_lint_checkers = ['pyflakes', 'pycodestyle']
let g:pymode_lint_ignore = ["E501"]

After (automatic):

  • Works immediately, no changes needed!

After (Ruff-specific):

let g:pymode_ruff_enabled = 1
let g:pymode_ruff_ignore = ["E501"]
" Ruff automatically includes F (pyflakes) and E/W (pycodestyle) rules

Scenario 2: Using autopep8 for formatting

Before:

" autopep8 was used automatically by :PymodeLintAuto

After:

let g:pymode_ruff_format_enabled = 1
" :PymodeLintAuto now uses Ruff format (faster!)

Scenario 3: Custom pylint configuration

Before:

let g:pymode_lint_checkers = ['pylint']
let g:pymode_lint_options_pylint = {'max-line-length': 100}

After:

let g:pymode_ruff_enabled = 1
" Use pyproject.toml for Ruff configuration:
" [tool.ruff]
" line-length = 100
" select = ["PLE", "PLR", "PLW"]  # pylint rules

Troubleshooting

Ruff not found

Error: ruff: command not found

Solution:

pip install ruff
# Verify:
ruff --version

Different formatting output

Issue: Ruff formats code differently than autopep8

Solution: This is expected. Ruff follows PEP 8 and Black formatting style. If you need specific formatting, configure Ruff via pyproject.toml:

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

Rule codes don't match

Issue: Some rule codes might differ between old tools and Ruff

Solution: See RUFF_CONFIGURATION_MAPPING.md for detailed rule mappings. Most common rules (E501, F401, etc.) are compatible.

Performance issues

Issue: Linting seems slower than expected

Solution:

  1. Ensure Ruff is installed: pip install ruff
  2. Check if legacy options are causing overhead (migrate to Ruff-specific options)
  3. Verify Ruff config file is being used

Breaking Changes

Removed Tools

The following tools are no longer available as separate checkers:

  • pylint (use Ruff PLE/PLR/PLW rules)
  • pyflakes (use Ruff F rules)
  • pycodestyle (use Ruff E/W rules)
  • mccabe (use Ruff C90 rules)
  • pep257 (use Ruff D rules)
  • autopep8 (use Ruff format)

Configuration Changes

  • g:pymode_lint_checkers values are mapped to Ruff rules (not actual tools)
  • g:pymode_lint_options_* are mapped to Ruff configuration
  • Old tool-specific options may not have exact equivalents

Behavior Changes

  • Formatting: Ruff format may produce slightly different output than autopep8
  • Linting: Ruff may report different errors than pylint/pyflakes (usually fewer false positives)
  • Performance: Should be significantly faster

Rollback Instructions

If you need to rollback to the old system:

  1. Checkout previous version:

    git checkout <previous-version-tag>

  2. Reinstall old dependencies (if needed):

    pip install pylint pyflakes pycodestyle mccabe pydocstyle autopep8

  3. Restore old configuration in your .vimrc

Note: The old tools are no longer maintained as submodules. You'll need to install them separately if rolling back.

Need Help?

Summary

✅ No immediate action required - your existing config works
✅ Install Ruff: pip install ruff
✅ Optional: Migrate to Ruff-specific options for better control
✅ Use Ruff config files: pyproject.toml or ruff.toml for project-specific settings
✅ Enjoy faster linting and formatting!