Introduction

 _    ______  ______
| |  / / __ \/ ____/
| | / / /_/ / __/
| |/ / ____/ /___     The Vim Python Extensions
|___/_/   /_____/

This is the documentation for version 0.7.3.

VPE provides a toolkit of modules and classes aimed at making it easier to extend Vim using modern Pythonic code. Its key features are:

• A Vim class and corresponding vim singleton which provides an API that is is extremely compatible with Vim’s built-in vim module, but includes extended capabilities.

  This makes it relatively easy to convert existing Python based Vim extensions and then start to take advantage of the Vim class’s extra features. See Switching from the vim module for how to do this.

• The vpe package, containing additional modules and classes which provide:

  • More pythonic APIs for some Vim features.

  • Extension modules and classes to help in writing plugins in Python.

• Support for plugins, using Python’s standard library entry-point mechanism.

Requirements

VPE requires a minimum of Vim 9.0 and Python 3.11.

User guide

• Installation
  • Installation on Linux
  • Installation on Windows
  • Installation problems
• Getting started
  • Switching from the vim module
  • Vim options
  • Vim vars and vvars
  • Vim registers
  • Access to Vim functions
  • Buffers, windows, tabpages, etc
  • Commands as functions
• Using Buffers
  • Always the same instance
  • Attributes and methods
  • Modifying contents
  • Buffer store
  • Temp options
• Using Windows
  • Basics
  • Attributes and methods
  • Context Managers
• The VPE and other logs
  • The vpe.log
  • Other logs
• Scratch buffers
  • ScratchBuffer creation
  • Displaying and updating
  • Managing the buffer
  • Subclassing ScratchBuffer
• Handling keys, events, etc.
  • Mapping key sequences
  • User defined commands
  • Events, aka auto-commands
  • Channels
  • Handling buffer changes
• Timers and deferred actions
  • The Timer class
  • Use of call_soon
• VPE plug-in mechanism
  • Vim’s default plug-in mechanism
  • Plug-in structure
  • Plug-in loading and initialisation
• Events, aka auto-commands
  • Defining commands
  • Using decorators
• User defined commands
  • Why user commands are tricky
  • Function define_command
  • The CommandHandler mix-in
  • The user_commands module
• Module vpe
  • Module vpe.app_ui_support
  • Module vpe.channels
  • Module vpe.config
  • Module vpe.core
  • Module vpe.diffs
  • Module vpe.mapping
  • Module vpe.message_bus
  • Module vpe.panels
  • Module vpe.syntax
  • Module vpe.ui
  • Module vpe.user_commands
  • Module vpe.windows
  • Module vpe.wrappers
  • VIM_DEFAULT
  • VI_DEFAULT
  • commands
  • log
  • vim
  • AutoCmdGroup
  • BufEventHandler
  • BufListener
  • Buffer
  • Buffers
  • Callback
  • CommandHandler
  • CommandInfo
  • Current
  • EventHandler
  • Finish
  • GlobalOptions
  • KeyHandler
  • Log
  • ManagedIOBuffer
  • OneShotTimer
  • Options
  • Popup
  • PopupAtCursor
  • PopupBeval
  • PopupDialog
  • PopupMenu
  • PopupNotification
  • Range
  • Registers
  • ScratchBuffer
  • Struct
  • TabPage
  • TabPages
  • Timer
  • Variables
  • Vim
  • VimError
  • Window
  • Windows
  • saved_current_window
  • saved_winview
  • temp_active_window
  • call_soon()
  • call_soon_once()
  • define_command()
  • dot_vim_dir()
  • echo_msg()
  • error_msg()
  • find_buffer_by_name()
  • get_display_buffer()
  • get_managed_io_buffer()
  • highlight()
  • pedit()
  • popup_clear()
  • script_py_path()
  • warning_msg()