Module vpe¶
Enhanced module for using Python3 in Vim.
This provides the Vim class, which is a wrapper around Vim’s built-in vim module. It is intended that a Vim instance can be uses as a replacement for the vim module. For example:
from vpe import vim
# Now use 'vim' as an extended version of the *vim* module.
# ...
This is compatible for versions of Vim from 8.0. It also needs Python 3.6 or newer.
The VPE module uses certain global Vim variables for its own internal purposes. The names are chosen to be suitably obscure, but obviously associated with VPE.
- _vpe_args_
This is a dictionary that is used by a Vim function to pass information to Python callback functions. Predefined entries are:
- ‘uid’
The unique ID for the callback function to be invoked.
- ‘args’
A sequence of any unnamed arguments passed to the Vim function.
Attributes
vpe.
vim
¶A replacement for (and wrapper around) the python-vim module.
This is in instance of the
Vim
class.
AutoCmdGroup¶
-
class
vpe.
AutoCmdGroup
(name)¶ A Pythonic way to define auto commands.
This is a context manager that supports definition of autocommands that:
Are always in a given group.
Invoke Python code when triggered.
It is intended to be used as:
with AutoCmdGroup('mygroup') as g: g.delete_all() g.add('BufWritePre', handle_bufwrite, ...) g.add('BufDelete', handle_bufdelete, ...) ... # Add more autocommands to the same group. with AutoCmdGroup('mygroup') as g: g.delete_all() g.add('BufWritePre', handle_bufwrite, ...)
Parameters
- name
The name of the group.
Static methods
-
static
add
(event, func, pat='<buffer>', once=False, nested=False)¶ Add a new auto command to the group.
Parameters
- event
The name of the event.
- func
The Python function to invoke. Plain functions and instance methods are supported.
- pat
The file pattern to match. If not supplied then the special ‘<buffer>’ pattern is used. If the argument is a
Buffer
then the special pattern for ‘buffer=N> is used.- once
The standard ‘:autocmd’ options.
- nested
The standard ‘:autocmd’ options.
-
static
delete_all
()¶ Delete all entries in the group.
Buffer¶
-
class
vpe.
Buffer
(buffer)¶ Wrapper around a python-buffer.
User code should not directly instantiate this class. VPE creates and manages instances of this class as required.
A number of extensions to the standard python-buffer are provided.
The
vars
property provides access to the buffer’s variables.The
list
context manager provides a clean, and often more efficient, way to access the buffer’s content.The
temp_options
context manager provides a clean way to work with a buffer with some of its options temporarily modified.Buffer specific meta-data can be attached using the
store
.The values provided by getbufinfo() are effectively available as properties of this class.
Properties
-
property
bufnr
→ int¶ The same as the
number
attribute.This exists as a side effect of providing getbufinfo() values as properties. It is more efficient to use the
number
attribute.
-
property
changed
→ int¶ Hidden flag; 0=buffer visible in a window, 1=buffer hidden.
-
property
changedtick
→ int¶ Same as changetick.
-
property
lastused
→ int¶ Time (in seconds) when buffer was last used.
This is a time in seconds a returned by localtime().
-
property
linecount
→ int¶ The number of lines in the buffer.
-
property
lnum
→ int¶ The current line number for the buffer.
-
property
loaded
→ int¶ Buffer loaded flag; 0=not loaded, 1=buffer loaded.
-
property
location
→ str¶ The location of the file loaded in this buffer.
- Returns
If the buffer is not associated with a file then an empty string. Otherwise the absolute directory part of the file’s name.
-
property
long_display_name
→ str¶ A long-form name for display purposes.
-
property
number
¶ The number of this buffer.
-
property
short_description
→ str¶ A short description for the buffer.
- Returns
For a quickfix window this is the title string. For a terminal this is the buffer’s name. For other types that are associated with a file the
location
property is provided.
-
property
short_display_name
→ str¶ A short-form name for display purposes.
-
property
type
→ str¶ The type name of this buffer.
This is similar to the ‘buftype’ option, but normal buffers have the type ‘normal’.
-
property
valid
→ bool¶ Test of this buffer is valid.
A buffer can become invalid if, for example, the underlying Vim buffer has been wiped out.
-
property
variables
→ int¶ The same as the
vars
attribute.This exists as a side effect of providing getbufinfo() values as properties. It is more efficient to use the
vars
attribute.
Methods
-
__getattr__
(name)¶ Make the values from getbufinfo() available as attributes.
This extends the base class implementation.
-
append
(line_or_lines, nr=None)¶ Append one or more lines to the buffer.
This is the same as using the append method of python-buffer.
Parameters
- line_or_lines
The line or lines to append.
- nr
If present then append after this line number.
-
goto_active_window
() → bool¶ Goto a window where this buffer is active.
Windows are search in the following order. The current window, windows in the current tab page, all windows in all tab pages.
This has no effect (and returns False) if the buffer is not active in any window.
Return value
True if an active window was found
-
list
()¶ A sequence context for efficient buffer modification.
As an example:
with vim.current.buffer.list() as lines: # Now lines is a copy of the buffers lines. lines[2:4] = ['one'] # Update lines in-place. # The vim.current.buffer has now been updated with modified lines.
Although this involves taking a copy of the buffer’s lines and then completely replacing the buffer’s set of lines, this is a much more efficient way to make non-trivial modifications to a buffer’s contents.
This will update the buffer, even if ‘modifiable’ is not set.
-
range
(a: int, b: int) → Range¶ Get a
Range
for the buffer.This is like getting a python-range object, except that it is wrapped in a
Range
instance.Parameters
- a: int
The start index of the range.
- b: int
The end index of the range. Note that this line is included in the range; i.e. the range is inclusive, unlike Python ranges.
-
store
(key: typing.Any) → Struct¶ Return a
Struct
for a give key.This provides a mechanism to store arbitrary data associated with a given buffer. A new
Struct
is created the first time a given key is used. An example of how this can be used:vim.current.buffer.store['my-store'].processed = True ... for buf in vim.buffers: if buf.store['my-store'].processed: # Treat already processed buffers differently. ...
The
vpe
package arranges to return the sameBuffer
instance for a given python-buffer so this effectively allows you to associated meta-data with individual Vim buffers.
-
temp_options
(**presets) → TemporaryOptions¶ Context used to temporarily change options.
This makes it easy, for example, to use a normally unmodifiable buffer to display information in a buffer. To update the displayed buffer’s contents do something like:
with disp_buf.temp_options(modifiable=True): disp.buf.append('Another line')
When the context ends, the modifiable option is reset to its original value. An alterative approach is:
with disp_buf.temp_options as opt: opt.modifiable = True disp.buf.append('Another line')
Only options set using presets or the context object are restored when the context exits.
Parameters
- presets
One or more options values may be defined using keyword arguments. The values are applied when the context is entered.
Class methods
-
classmethod
get_known
(buffer: typing.Any) → Optional[ForwardRef(‘Buffer’)]¶ Get the Buffer instance for a given vim.buffer.
This is only intended for internal use.
Parameters
- buffer: typing.Any
A standard python-buffer.
Buffers¶
-
class
vpe.
Buffers
(obj=None)¶ Wrapper around the built-in vim.buffers.
User code should not directly instantiate this class. VPE creates and manages instances of this class as required.
This is a proxy that extends the vim.Buffer behaviour in various ways.
GlobalOptions¶
-
class
vpe.
GlobalOptions
(vim_options)¶ Wrapper for vim.options, etc.
This extends the behaviour so that options appear as attributes. The standard dictionary style access still works.
Log¶
-
class
vpe.
Log
(name, maxlen=500)¶ Support for logging to a display buffer.
An instance of this class provides a mechanism to support logging that can be viewed within a buffer. Instances of this class act as a simple print function.:
info = Log('my_info') info("Created log", info) info("Starting process")
The output is stored in a Python FIFO structure, up to a maximum number of lines; the default is 500, change this with
set_maxlen
. No actual Vim buffer is created until required, which is whenshow
is first invoked.:info.show() # Make the log visible.
The
vpe
module provides a predefined log, called ‘VPE’. This is available for general use. VPE also uses it to log significant occurrences - mainly error conditions.Parameters
- name
A name that maps to the corresponding display buffer.
- maxlen
The maximum number of lines to store.
Attributes
Methods
-
__call__
(*args)¶ Write to the log.
The arguments are formatted using
print
and then appended to the log buffer, with a time stamp.Parameters
- args
The same as for Python’s print function.
-
clear
() → None¶ Clear all lines from the log.
The FIFO is cleared and the corresponding buffer updated.
-
flush
()¶ File like I/O support.
-
redirect
()¶ Redirect stdout/stderr to the log.
-
set_maxlen
(maxlen: int) → None¶ Set the maximum length of the log’s FIFO.
This will discard older lines if necessary.
Parameters
- maxlen: int
How many lines to store in the FIFO.
-
show
() → None¶ Make sure the buffer is visible.
If there is no buffer currently displayed the log then this will:
Split the current window.
Create a buffer and show it in the new split.
-
unredirect
()¶ Undo most recent redirection.
-
write
(s)¶ Write a string to the log buffer.
Parameters
- s
The string to write.
Popup¶
-
class
vpe.
Popup
(content, **p_options)¶ A Pythonic way to use Vim’s popup windows.
This can be used as instead of the individual functions popup_create, popup_hide, popup_show, popup_settext, popup_close).
Creation of a Popup uses vim.popup_create to create the actual popup window. Control of the popup windows is achieved using the methods
hide
,show
andsettext
. You can subclass this in order to override theon_close
oron_key
methods.The subclasses
PopupAtCursor
,PopupBeval
,PopupNotification
,PopupDialog
andPopupMenu
, provide similar convenient alternatives to popup_atcursor, popup_beval, popup_notification, popup_dialog and popup_menu.The windows options (line, col, pos, etc.) are made avaiable as properties of the same name. For example, to change the first displated line:
p = vpe.Popup(my_text) ... p.firstline += 3
The close option must be accessed as close_control, because
close
is a Popup method. There is no filter or callback property.Parameters
Properties
Methods
-
close
(result: int = 0) → None¶ Close the popup.
Parameters
- result: int
The result value that will be forwarded to on_close.
-
hide
() → None¶ Hide the popup.
-
on_close
(result: int) → None¶ Invoked when the popup is closed.
The default implementation does nothing, it is intended that this be over-ridden in subclasses.
Parameters
- result: int
The value passed to
close
. This will be -1 if the user forcefully closed the popup.
-
on_key
(key: str, byte_seq: bytes) → bool¶ Invoked when the popup receives a keypress.
The default implementation does nothing, it is intended that this be over-ridden in subclasses. The keystream is preprocessed before this is method is invoked as follows:
Merged key sequences are split, so that this is always invoked with the sequence for just a single key.
Special key sequences are converted to the standard Vim symbolic names such as <Up>, <LeftMouse>, <F11>, <S-F3>, <C-P>, etc.
Anything that does not convert to a special name is decoded to a Python string, if possible.
Parameters
- key: str
The pressed key. This is typically a single character such as ‘a’ or a symbolic Vim keyname, such as ‘<F1>’.
- byte_seq: bytes
The unmodified byte sequence, as would be received for a filter callback using Vimscript.
Return value
True if the key should be considered consumed.
-
settext
(content) → None¶ Set the text of the popup.
-
show
() → None¶ Show the popup.
Class methods
-
classmethod
clear
(force: bool) → None¶ Clear all popups from display.
Use this in preference to vim.popup_clear, to ensure that VPE cleans up its underlying administrative structures.
Parameters
- force: bool
If true then if the current window is a popup, it will also be closed.
-
PopupAtCursor¶
-
class
vpe.
PopupAtCursor
(content, **p_options)¶ Popup configured to appear near the cursor.
This creates the popup using popup_atcursor().
PopupBeval¶
-
class
vpe.
PopupBeval
(content, **p_options)¶ Popup configured to appear near (v:beval_line, v:beval_col).
This creates the popup using popup_beval().
PopupDialog¶
-
class
vpe.
PopupDialog
(content, **p_options)¶ Popup configured as a dialogue.
This creates the popup using popup_dialog(). It also provides a default
PopupDialog.on_key
implementation that invokes popup_filter_yesno.Methods
-
on_key
(key, byte_seq)¶ Invoke popup_filter_yesno to handle keys for this popup.
-
PopupNotification¶
-
class
vpe.
PopupNotification
(content, **p_options)¶ Popup configured as a short lived notification (default 3s).
This creates the popup using popup_notification().
Range¶
-
class
vpe.
Range
(obj=None)¶ Wrapper around the built-in vim.Range type.
User code should not directly instantiate this class.
Methods
-
append
(line_or_lines, nr=None)¶ Append one or more lines to the range.
This is the same as using the append method of python-range.
Parameters
- line_or_lines
The line or lines to append.
- nr
If present then append after this line number.
-
Registers¶
-
class
vpe.
Registers
¶ Dictionary like access to the Vim registers.
This allows Vim’s registers to be read and modified. This is typically via the
Vim.registers
attribute.:vim.registers['a'] = 'A line of text' prev_copy = vim.registers[1]
This uses eval’ to read registers and :vim:`setreg to write them. Keys are converted to strings before performing the register lookup. When the key is the special ‘=’ value, the un-evaluated contents of the register is returned.
Methods
-
__getitem__
(reg_name: Union[str, int]) → typing.Any¶ Allow reading registers as dictionary entries.
The reg_name may also be an integer value in the range 0-9.
-
__setitem__
(reg_name: Union[str, int], value: typing.Any)¶ Allow setting registers as dictionary entries.
The reg_name may also be an integer value in the range 0-9.
-
ScratchBuffer¶
-
class
vpe.
ScratchBuffer
(name, buffer)¶ A scratch buffer.
A scratch buffer has no associated file, has no swap file, never gets written and never appears to be modified. The content of such a buffer is typically under the control of plugin code. Direct editing is disabled.
Direct instantiation is not recommended; use
get_display_buffer
, which creates bufferes with suitably formatted names.Methods
-
modifiable
() → TemporaryOptions¶ Create a context that allows the buffer to be modified.
-
show
(splitlines: Optional[int] = None) → bool¶ Make this buffer visible.
Without a splitlines argument, this will use the current window to show this buffer. If the splitlines argument is provided and greater than zero then:
The current window is split.
The lower split is set to be splitlines high.
This buffer is displayed in the upper window.
Parameters
- splitlines: typing.Optional[int]
Number of lines to leave in the bottom window.
Return value
True if the window is successfully split.
-
Struct¶
-
class
vpe.
Struct
¶ A basic data storage structure.
This is intended to store arbitrary name, value pairs as attributes. Attempting to read an undefined attribute gives
None
.This is provided primarily to support the
Buffer.store
mechanism. Direct use of this class is not intended as part of the API.Methods
TabPage¶
-
class
vpe.
TabPage
(obj=None)¶ Wrapper around a python-tabpage.
User code should not directly instantiate this class. VPE creates and manages instances of this class as required.
This is a proxy that extends the vim.Window behaviour in various ways.
Properties
TabPages¶
-
class
vpe.
TabPages
(obj=None)¶ Wrapper around the built-in vim.tabpages.
User code should not directly instantiate this class. VPE creates and manages instances of this class as required.
This is a proxy that extends the vim.TabPages behaviour in various ways.
Static methods
-
static
new
(position='after')¶ Create a new tab page.
Parameters
- position
The position relative to this tab. The standard character prefixes for the :tabnew command can be used or one of the more readable strings:
- ‘after’, ‘before’
Immediately after or before the current tab (same as ‘.’, ‘-‘),
- ‘first’, ‘last’
As the first or last tab (same as ‘0’, ‘$’),
This defaults to ‘after’.
-
static
Timer¶
-
class
vpe.
Timer
(ms, func, repeat=None)¶ Pythonic way to use Vim’s timers.
This can be used as a replacement for the vim functions: timer_start, timer_info, timer_pause, timer_stop.
An example of usage:
def handle_expire(t): print(f'Remaining repeats = {t.repeat}') # This will cause handle_expire to be called twice. The output will be: # t.repeat=2 # t.repeat=1 t = Timer(ms=100, handle_expire, repeat=2)
The status of a timer can be queried using the properties
time
,repeat
,remaining
andpaused
. The methodspause
,stop
andresume
allow an active timer to be controlled.Parameters
- ms
The timer’s interval in milliseconds.
- func
The function to be invoked when the timer fires. This is called with the firing
Timer
instance as the only parameter.- repeat
How many times to fire.
Attributes
Properties
-
property
id
→ int¶ The ID of the underlying vim timer.
-
property
paused
→ bool¶ True if the timer is currently paused.
-
property
remaining
→ int¶ The time remaining (ms) until the timer will next fire.
-
property
repeat
→ int¶ The number of times the timer will still fire.
Note that this is 1, during the final callback - not zero.
-
property
time
→ int¶ The time value used to create the timer.
Methods
Class methods
-
classmethod
stop_all
()¶ Stop all timers and clean up.
Use this in preference to vim.timer_stopall, to ensure that VPE cleans up its underlying administrative structures.
Variables¶
-
class
vpe.
Variables
(obj=None)¶ Wrapper around the various vim variable dictionaries.
This allows entries to be modified.
Vim¶
-
class
vpe.
Vim
(*args, **kwargs)¶ A wrapper around and replacement for the vim module.
This is a instance object not a module, but it provides a API that is extremely compatible with the python-vim module.
Properties
-
property
buffers
→ Buffers¶ A read-only container of the all the buffers.
-
property
current
→ Current¶ Convenient access to currently active objects.
Note: Does not support assigment to window, buffer or tabpage.
-
property
error
→ Type[vim.error]¶ The plain built-in Vim exception (python-error).
-
property
options
→ GlobalOptions¶ An object providing access to Vim’s global options.
-
property
registers
→ `Registers`¶ Dictionary like access to Vim’s registers.
This returns a
Registers
object.
-
property
tabpages
→ TabPages¶ A read-only container of the all the tab pages.
-
property
vars
→ Variables¶ An object providing access to global Vim variables.
-
property
vvars
→ Variables¶ An object providing access to Vim (v:) variables.
-
property
windows
→ Windows¶ A read-only container of the windows of the current tab page.
Methods
-
command
(cmd: str) → None¶ Execute an Ex command.
Parameters
- cmd: str
The Ex command to execute:
Exceptions raised
- VimError
A more detailed version vim.error (python-error).
-
eval
(expr: str) → Union[dict, list, str]¶ Evaluate a Vim expression.
Return value
A dict, list or string. See python-eval for details.
Exceptions raised
- VimError
A more detailed version vim.error (python-error).
-
temp_options
(**presets) → TemporaryOptions¶ Context used to temporarily change options.
Static methods
-
property
VimError¶
-
class
vpe.
VimError
(error: vim.error)¶ A parsed version of vim.error.
VPE code raises this in place of the standard vim.error exception. It is a subclass of vim.error, so code that handles vim.error will still work when converted to use the
vpe.vim
object.This exception attempts to parse the Vim error string to provide additional attributes:
Attributes
-
code
: int:¶ The error code. This will be zero if parsing failed to extract the code.
-
command
: str:¶ The name of the Vim command that raised the error. This may be an empty string.
-
message
: str:¶ The message part, after extracting the command, error code and ‘Vim’ prefix. If parsing completely fails then is simply the unparsed message.
-
Window¶
-
class
vpe.
Window
(window)¶ Wrapper around a python-window.
User code should not directly instantiate this class. VPE creates and manages instances of this class as required.
This is a proxy that extends the vim.Window behaviour in various ways.
Attributes
Properties
Methods
-
goto
() → bool¶ Switch to this window, if possible.
Return value
True if the current window was set successfully.
-
temp_options
(**presets) → TemporaryOptions¶ Context used to temporarily change options.
This does for a window what
Buffer.temp_options
does for buffer.
-
Windows¶
-
class
vpe.
Windows
(obj=None)¶ Wrapper around the built-in vim.windows.
User code should not directly instantiate this class. VPE creates and manages instances of this class as required.
Parameters
- obj
A python-windows object.
saved_winview¶
-
class
vpe.
saved_winview
¶ Context manager that saves and restores the current window’s view.
call_soon¶
-
vpe.
call_soon
(func)¶ Arrange to call a function ‘soon’.
This uses a Vim timer with a delay of 0ms to schedule the function call. This means that currently executing Python code will complete before the function is invoked.
Parameters
- func
The function to be invoked. It takes no arguments.
error_msg¶
-
vpe.
error_msg
(*args)¶ A print-like function that writes an error message.
Unlike using sys.stderr directly, this does not raise a vim.error.
find_buffer_by_name¶
-
vpe.
find_buffer_by_name
(name: str) → Optional[Buffer]¶ Find the buffer with a given name.
The name must be an exact match.
Parameters
- name: str
The name of the buffer to find.
get_display_buffer¶
-
vpe.
get_display_buffer
(name: str) → ScratchBuffer¶ Get a named display-only buffer.
The actual buffer name will be of the form ‘/[[name]]’. The buffer is created if it does not already exist.
Parameters
- name: str
An identifying name for this buffer.
highlight¶
-
vpe.
highlight
(...)¶ highlight( *, group=None, clear=False, default=False, link=None, disable=False, **kwargs)
Python version of the highlight command.
This provides keyword arguments for all the command parameters. These are generally taken from the :highlight command’s documentation.
Parameters
- group
The name of the group being defined. If omitted then all other arguments except clear are ignored.
- clear
If set then the command
highlight clear [<group>]
is generated. All other arguments are ignored.- disable
If set then the specified group is disabled using the command:
highlight <group> NONE
- link
If set then a link command will be generated of the form:
highlight link <group> <link>
.Other arguments are ignored.
- default
If set then the generated command has the form
highlight default...
.- kwargs
The remain keyword arguments act like the :highlight command’s keyword arguments.
pedit¶
-
vpe.
pedit
(path: str, silent=True, noerrors=False)¶ Edit file in the preview window.
Parameters
- path: str
The files path.
- silent
If true then run the :pedit command silently.
- noerrors
If true then add ‘!’ to suppress errors.
popup_clear¶
-
vpe.
popup_clear
(force=False)¶ Convenience function that invokes
Popup.clear
.
script_py_path¶
-
vpe.
script_py_path
() → str¶ Derive a python script name from the current Vim script name.
timer_stopall¶
-
vpe.
timer_stopall
()¶ Convenience function that invokes
Timer.stop_all
.
version¶
-
vpe.
version
() → Tuple[int, int, int]¶ The current VPE version as a 3 part tuple.
The tuple follows the conventions of semantic versioning 2.0 (https://semver.org/); i.e. (major, minor, patch).