Improve section movement for Python

Section Movement in Vim

Section movement in Vim maps these keys for nroff macros and C functions:

• ]] Move sections forward or to the next { in the first column
• ][ Move sections forward or to the next } in the first column
• [[ Move sections backward or to the previous { in the first column
• [] Move sections backward or to the previous } in the first column

Following this precedent, Vim supports section movement for other languages. For Python, the mappings allow Python developers to navigate global classes and functions:

let b:next_toplevel='\v%$\|^(class\|def\|async def)>'
let b:prev_toplevel='\v^(class\|def\|async def)>'
let b:next_endtoplevel='\v%$\|\S.*\n+(def\|class)'
let b:prev_endtoplevel='\v\S.*\n+(def\|class)'

if !exists('g:no_plugin_maps') && !exists('g:no_python_maps')
    execute "nnoremap <silent> <buffer> ]] :<C-U>call <SID>Python_jump('n', '". b:next_toplevel."', 'W', v:count1)<cr>"
    execute "nnoremap <silent> <buffer> [[ :<C-U>call <SID>Python_jump('n', '". b:prev_toplevel."', 'Wb', v:count1)<cr>"
    execute "nnoremap <silent> <buffer> ][ :<C-U>call <SID>Python_jump('n', '". b:next_endtoplevel."', 'W', v:count1, 0)<cr>"
    execute "nnoremap <silent> <buffer> [] :<C-U>call <SID>Python_jump('n', '". b:prev_endtoplevel."', 'Wb', v:count1, 0)<cr>"

There is also a set of mappings for nested classes and methods:

let b:next='\v%$\|^\s*(class\|def\|async def)>'
let b:prev='\v^\s*(class\|def\|async def)>'
let b:next_end='\v\S\n*(%$\|^(\s*\n*)*(class\|def\|async def)\|^\S)'
let b:prev_end='\v\S\n*(^(\s*\n*)*(class\|def\|async def)\|^\S)'

    execute "nnoremap <silent> <buffer> ]m :<C-U>call <SID>Python_jump('n', '". b:next."', 'W', v:count1)<cr>"
    execute "nnoremap <silent> <buffer> [m :<C-U>call <SID>Python_jump('n', '". b:prev."', 'Wb', v:count1)<cr>"
    execute "nnoremap <silent> <buffer> ]M :<C-U>call <SID>Python_jump('n', '". b:next_end."', 'W', v:count1, 0)<cr>"
    execute "nnoremap <silent> <buffer> [M :<C-U>call <SID>Python_jump('n', '". b:prev_end."', 'Wb', v:count1, 0)<cr>"

Section Movement in VSCodeVim

VSCodeVim has Python-specific code for section movement. MoveSectionBoundary delegates to PythonDocument.moveClassBoundary, which navigates classes only. Python developers editing files without classes will be surprised that ]] and related keys do nothing.

To navigate global functions in VSCodeVim. developers must use ]m and related keys.

Proposal

If Vim compatibility is a goal of VSCodeVim, then section movement should navigate global classes and functions in Python. If this is agreed, then we must decide how to migrate the current behavior.

Options include:

1. Update VSCodeVim to conform with Vim behavior, and flag the change in release notes.

2. Update VSCodeVim, and also provide mappings for the current behavior. An obvious suggestion is ]c for class, analagous to ]m for method.

3. Update VSCodeVim, but hide the new behavior behind an option.

Suggestions?

Start with src/actions/motion.ts at MoveSectionBoundary and src/actions/languages/python/motion.ts at PythonDocument.moveClassBoundary. Compare the current behavior with Vim's runtime/ftplugin/python.vim mappings and the linked motion documentation. Done means settling the migration choice and implementing the selected compatibility behavior, including any mappings or release-note changes required by that choice.