add: support for ruff as a Python linter and fixer (#4347)

this commit adds ruff as both a Python linter and fixer, together with
some tests and documentation.

ruff repo: https://github.com/charliermarsh/ruff

ale_linters/python/ruff.vim

@@ -0,0 +1,84 @@
+" Author: Yining <zhang.yining@gmail.com>
+" Description: ruff as linter for python files
+
+call ale#Set('python_ruff_executable', 'ruff')
+call ale#Set('python_ruff_options', '')
+call ale#Set('python_ruff_use_global', get(g:, 'ale_use_global_executables', 0))
+call ale#Set('python_ruff_change_directory', 1)
+call ale#Set('python_ruff_auto_pipenv', 0)
+call ale#Set('python_ruff_auto_poetry', 0)
+
+call ale#fix#registry#Add('ruff',
+\   'ale#fixers#ruff#Fix',
+\   ['python'],
+\   'A python linter/fixer for Python written in Rust'
+\)
+
+function! ale_linters#python#ruff#GetExecutable(buffer) abort
+    if (ale#Var(a:buffer, 'python_auto_pipenv') || ale#Var(a:buffer, 'python_ruff_auto_pipenv'))
+    \ && ale#python#PipenvPresent(a:buffer)
+        return 'pipenv'
+    endif
+
+    if (ale#Var(a:buffer, 'python_auto_poetry') || ale#Var(a:buffer, 'python_ruff_auto_poetry'))
+    \ && ale#python#PoetryPresent(a:buffer)
+        return 'poetry'
+    endif
+
+    return ale#python#FindExecutable(a:buffer, 'python_ruff', ['ruff'])
+endfunction
+
+function! ale_linters#python#ruff#GetCwd(buffer) abort
+    if ale#Var(a:buffer, 'python_ruff_change_directory')
+        " Run from project root if found, else from buffer dir.
+        let l:project_root = ale#python#FindProjectRoot(a:buffer)
+
+        return !empty(l:project_root) ? l:project_root : '%s:h'
+    endif
+
+    return ''
+endfunction
+
+function! ale_linters#python#ruff#GetCommand(buffer, version) abort
+    let l:executable = ale_linters#python#ruff#GetExecutable(a:buffer)
+    let l:exec_args = l:executable =~? 'pipenv\|poetry$'
+    \   ? ' run ruff'
+    \   : ''
+
+    " NOTE: ruff version `0.0.69` supports liniting input from stdin
+    return ale#Escape(l:executable) . l:exec_args
+    \   . ale#Pad(ale#Var(a:buffer, 'python_ruff_options'))
+    \   . ' --format text'
+    \   .  (ale#semver#GTE(a:version, [0, 0, 69]) ? ' -' : ' %s')
+endfunction
+
+function! ale_linters#python#ruff#Handle(buffer, lines) abort
+    "Example: path/to/file.py:10:5: E999 SyntaxError: unexpected indent
+    let l:pattern = '\v^[a-zA-Z]?:?[^:]+:(\d+):(\d+)?:? (.+)$'
+    let l:output = []
+
+    for l:match in ale#util#GetMatches(a:lines, l:pattern)
+        call add(l:output, {
+        \   'lnum': l:match[1] + 0,
+        \   'col': l:match[2] + 0,
+        \   'text': l:match[3],
+        \})
+    endfor
+
+    return l:output
+endfunction
+
+call ale#linter#Define('python', {
+\   'name': 'ruff',
+\   'executable': function('ale_linters#python#ruff#GetExecutable'),
+\   'cwd': function('ale_linters#python#ruff#GetCwd'),
+\   'command': {buffer -> ale#semver#RunWithVersionCheck(
+\       buffer,
+\       ale_linters#python#ruff#GetExecutable(buffer),
+\       '%e --version',
+\       function('ale_linters#python#ruff#GetCommand'),
+\   )},
+\   'callback': 'ale_linters#python#ruff#Handle',
+\   'output_stream': 'both',
+\   'read_buffer': 1,
+\})

autoload/ale/fixers/ruff.vim

@@ -0,0 +1,54 @@
+" Author: Yining <zhang.yining@gmail.com>
+" Description: ruff as ALE fixer for python files
+
+function! ale#fixers#ruff#GetCwd(buffer) abort
+    if ale#Var(a:buffer, 'python_ruff_change_directory')
+        " Run from project root if found, else from buffer dir.
+        let l:project_root = ale#python#FindProjectRoot(a:buffer)
+
+        return !empty(l:project_root) ? l:project_root : '%s:h'
+    endif
+
+    return ''
+endfunction
+
+function! ale#fixers#ruff#GetExecutable(buffer) abort
+    if (ale#Var(a:buffer, 'python_auto_pipenv') || ale#Var(a:buffer, 'python_ruff_auto_pipenv'))
+    \ && ale#python#PipenvPresent(a:buffer)
+        return 'pipenv'
+    endif
+
+    if (ale#Var(a:buffer, 'python_auto_poetry') || ale#Var(a:buffer, 'python_ruff_auto_poetry'))
+    \ && ale#python#PoetryPresent(a:buffer)
+        return 'poetry'
+    endif
+
+    return ale#python#FindExecutable(a:buffer, 'python_ruff', ['ruff'])
+endfunction
+
+function! ale#fixers#ruff#GetCommand(buffer, version) abort
+    let l:executable = ale_linters#python#ruff#GetExecutable(a:buffer)
+    let l:exec_args = l:executable =~? 'pipenv\|poetry$'
+    \   ? ' run ruff'
+    \   : ''
+
+    " NOTE: ruff version `0.0.72` implement `--fix` with stdin
+    return ale#Escape(l:executable) . l:exec_args
+    \   . ale#Pad(ale#Var(a:buffer, 'python_ruff_options'))
+    \   . ' --fix'
+    \   .  (ale#semver#GTE(a:version, [0, 0, 72]) ? ' -' : ' %s')
+endfunction
+
+function! ale#fixers#ruff#Fix(buffer) abort
+    let l:fix_cmd = {buffer -> ale#semver#RunWithVersionCheck(
+    \     buffer,
+    \     ale#fixers#ruff#GetExecutable(buffer),
+    \     '%e --version',
+    \     function('ale#fixers#ruff#GetCommand'),
+    \ )}(a:buffer)
+
+    return {
+    \ 'cwd': ale#fixers#ruff#GetCwd(a:buffer),
+    \ 'command': l:fix_cmd,
+    \}
+endfunction

doc/ale-python.txt

@@ -1115,6 +1115,69 @@ g:ale_python_reorder_python_imports_use_global
   See |ale-integrations-local-executables|
 
 
+===============================================================================
+ruff                                                          *ale-python-ruff*
+
+g:ale_python_ruff_change_directory         *g:ale_python_ruff_change_directory*
+                                           *b:ale_python_ruff_change_directory*
+  Type: |Number|
+  Default: `1`
+
+  If set to `1`, `ruff` will be run from a detected project root, per
+  |ale-python-root|. if set to `0` or no project root detected,
+  `ruff` will be run from the buffer's directory.
+
+
+g:ale_python_ruff_executable                     *g:ale_python_ruff_executable*
+                                                 *b:ale_python_ruff_executable*
+  Type: |String|
+  Default: `'ruff'`
+
+  See |ale-integrations-local-executables|
+
+  Set this to `'pipenv'` to invoke `'pipenv` `run` `ruff'`.
+  Set this to `'poetry'` to invoke `'poetry` `run` `ruff'`.
+
+
+g:ale_python_ruff_options                           *g:ale_python_ruff_options*
+                                                    *b:ale_python_ruff_options*
+  Type: |String|
+  Default: `''`
+
+  This variable can be changed to add command-line arguments to the ruff
+  invocation.
+
+  For example, to select/enable and/or disable some error codes,
+  you may want to set >
+  let g:ale_python_ruff_options = '--ignore F401'
+
+
+g:ale_python_ruff_use_global                     *g:ale_python_ruff_use_global*
+                                                 *b:ale_python_ruff_use_global*
+  Type: |Number|
+  Default: `get(g:, 'ale_use_global_executables', 0)`
+
+  See |ale-integrations-local-executables|
+
+
+g:ale_python_ruff_auto_pipenv                   *g:ale_python_ruff_auto_pipenv*
+                                                *b:ale_python_ruff_auto_pipenv*
+  Type: |Number|
+  Default: `0`
+
+  Detect whether the file is inside a pipenv, and set the executable to `pipenv`
+  if true. This is overridden by a manually-set executable.
+
+
+g:ale_python_ruff_auto_poetry                   *g:ale_python_ruff_auto_poetry*
+                                                *b:ale_python_ruff_auto_poetry*
+  Type: |Number|
+  Default: `0`
+
+  Detect whether the file is inside a poetry, and set the executable to `poetry`
+  if true. This is overridden by a manually-set executable.
+
+
 ===============================================================================
 unimport                                                  *ale-python-unimport*
 

doc/ale-supported-languages-and-tools.txt

@@ -483,6 +483,7 @@ Notes:
   * `pyre`
   * `pyright`
   * `reorder-python-imports`
+  * ruff
   * `unimport`
   * `vulture`!!
   * `yapf`

doc/ale.txt

@@ -3160,6 +3160,7 @@ documented in additional help files.
     pyre..................................|ale-python-pyre|
     pyright...............................|ale-python-pyright|
     reorder-python-imports................|ale-python-reorder_python_imports|
+    ruff..................................|ale-python-ruff|
     unimport..............................|ale-python-unimport|
     vulture...............................|ale-python-vulture|
     yapf..................................|ale-python-yapf|

supported-tools.md

@@ -492,6 +492,7 @@ formatting.
   * [pyre](https://github.com/facebook/pyre-check) :warning:
   * [pyright](https://github.com/microsoft/pyright)
   * [reorder-python-imports](https://github.com/asottile/reorder_python_imports)
+  * [ruff](https://github.com/charliermarsh/ruff)
   * [unimport](https://github.com/hakancelik96/unimport)
   * [vulture](https://github.com/jendrikseipp/vulture) :warning: :floppy_disk:
   * [yapf](https://github.com/google/yapf)

test/linter/test_ruff.vader

@@ -0,0 +1,105 @@
+Before:
+  Save g:ale_python_auto_pipenv
+
+  let g:ale_python_auto_pipenv = 0
+
+  call ale#assert#SetUpLinterTest('python', 'ruff')
+
+  let b:bin_dir = has('win32') ? 'Scripts' : 'bin'
+  let b:command_tail = ' --format text -'
+
+  GivenCommandOutput ['ruff 0.0.83']
+
+After:
+  unlet! b:bin_dir
+  unlet! b:executable
+  unlet! b:command_tail
+
+  call ale#assert#TearDownLinterTest()
+
+Execute(The ruff callbacks should return the correct default values):
+  AssertLinterCwd expand('%:p:h')
+  AssertLinter 'ruff', ale#Escape('ruff') . b:command_tail
+
+Execute(ruff should run with the file path of buffer in old versions):
+  " version `0.0.69` supports liniting input from stdin
+  GivenCommandOutput ['ruff 0.0.68']
+
+  AssertLinterCwd expand('%:p:h')
+  AssertLinter 'ruff', ale#Escape('ruff') . b:command_tail[:-3] . ' %s'
+
+Execute(ruff should run with the stdin in new enough versions):
+  GivenCommandOutput ['ruff 0.0.83']
+
+  AssertLinterCwd expand('%:p:h')
+  AssertLinter 'ruff', ale#Escape('ruff') . b:command_tail[:-3] . ' -'
+  " AssertLinter 'ruff', ale#Escape('ruff') . b:command_tail[:-3] . '--format text -'
+
+Execute(The option for disabling changing directories should work):
+  let g:ale_python_ruff_change_directory = 0
+
+  AssertLinterCwd ''
+  AssertLinter 'ruff', ale#Escape('ruff') . b:command_tail
+
+Execute(The ruff executable should be configurable, and escaped properly):
+  let g:ale_python_ruff_executable = 'executable with spaces'
+
+  AssertLinter 'executable with spaces', ale#Escape('executable with spaces') . b:command_tail
+
+Execute(The ruff command callback should let you set options):
+  let g:ale_python_ruff_options = '--some-flag'
+  AssertLinter 'ruff', ale#Escape('ruff') . ' --some-flag' . b:command_tail
+
+  let g:ale_python_ruff_options = '--some-option value'
+  AssertLinter 'ruff', ale#Escape('ruff') . ' --some-option value' . b:command_tail
+
+Execute(The ruff callbacks shouldn't detect virtualenv directories where they don't exist):
+  call ale#test#SetFilename('../test-files/python/no_virtualenv/subdir/foo/bar.py')
+
+  AssertLinterCwd ale#path#Simplify(g:dir . '/../test-files/python/no_virtualenv/subdir')
+  AssertLinter 'ruff', ale#Escape('ruff') . b:command_tail
+
+Execute(The ruff callbacks should detect virtualenv directories):
+  call ale#test#SetFilename('../test-files/python/with_virtualenv/subdir/foo/bar.py')
+  let b:executable = ale#path#Simplify(
+  \ g:dir . '/../test-files/python/with_virtualenv/env/' . b:bin_dir . '/ruff'
+  \)
+  AssertLinterCwd ale#path#Simplify(g:dir . '/../test-files/python/with_virtualenv/subdir')
+  AssertLinter b:executable, ale#Escape(b:executable) . b:command_tail
+
+Execute(You should able able to use the global ruff instead):
+  call ale#test#SetFilename('../test-files/python/with_virtualenv/subdir/foo/bar.py')
+  let g:ale_python_ruff_use_global = 1
+
+  AssertLinterCwd ale#path#Simplify(g:dir . '/../test-files/python/with_virtualenv/subdir')
+  AssertLinter 'ruff', ale#Escape('ruff') . b:command_tail
+
+Execute(Setting executable to 'pipenv' appends 'run ruff'):
+  let g:ale_python_ruff_executable = 'path/to/pipenv'
+  let g:ale_python_ruff_use_global = 1
+
+  AssertLinter 'path/to/pipenv', ale#Escape('path/to/pipenv') . ' run ruff'
+  \   . ' --format text -'
+
+Execute(Pipenv is detected when python_ruff_auto_pipenv is set):
+  let g:ale_python_ruff_auto_pipenv = 1
+  call ale#test#SetFilename('../test-files/python/pipenv/whatever.py')
+
+  AssertLinterCwd expand('%:p:h')
+  AssertLinter 'pipenv', ale#Escape('pipenv') . ' run ruff'
+  \   . ' --format text -'
+
+Execute(Setting executable to 'poetry' appends 'run ruff'):
+  let g:ale_python_ruff_executable = 'path/to/poetry'
+  let g:ale_python_ruff_use_global = 1
+
+  AssertLinter 'path/to/poetry', ale#Escape('path/to/poetry') . ' run ruff'
+  \   . ' --format text -'
+
+Execute(poetry is detected when python_ruff_auto_poetry is set):
+  let g:ale_python_ruff_auto_poetry = 1
+  call ale#test#SetFilename('../test-files/python/poetry/whatever.py')
+
+  AssertLinterCwd expand('%:p:h')
+  AssertLinter 'poetry', ale#Escape('poetry') . ' run ruff'
+  \   . ' --format text -'