Module vpe.core¶
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.
# ...
Callback¶
-
class
vpe.core.
Callback
(...)¶ Callback( func, *, py_args=(), py_kwargs={}, vim_exprs=(), pass_bytes=False, once=False, **kwargs)
Wrapper for a function to be called from Vim.
This encapsulates the mechanism used to arrange for a Python function to be invoked in response to an event in the ‘Vim World’. A Callback stores the Python function together with an ID that is uniquely associated with the function (the UID). If, for example this wraps function ‘spam’ giving it UID=42 then the Vim script code:
:call VPE_Call(42, 'hello', 123)
will result in the Python function ‘spam’ being invoked as:
spam('hello', 123)
The way this works is that the VPE_Call function first stores the UID and arguments in the global Vim variable _vpe_args_ in a dictionary as:
{ 'uid': 42, 'args': ['hello', 123] }
Then it calls this class’s
invoke
method:return py3eval('vpe.Callback.invoke()')
The
invoke
class method extracts the UID and uses it to find the Callback instance.Parameters
- func
The Python function to be called back.
- py_args
Addition positional arguments to be passed to func.
- py_kwargs
Additional keyword arguments to be passed to func.
- vim_exprs
Expressions used as positional arguments for the VPE_Call helper function.
- pass_bytes
If true then vim byte-strings will not be decoded to Python strings.
- kwargs
Additional info to store with the callback. This is used by subclasses - see ‘MapCallback’ for an example.
Methods
-
as_call
()¶ Format a command of the form ‘call VPE_xxx(…)’
The result can be used as a colon prompt command.
-
as_invocation
()¶ Format a command of the form ‘VPE_xxx(…)’
The result is a valid Vim script expression.
-
as_vim_function
()¶ Create a vim.Function that will route to this callback.
-
format_call_fail_message
()¶ Generate a message to give details of a failed callback invocation.
This is used when the
Callback
instance exists, but the call raised an exception.
-
get_call_args
(_vpe_args: Dict[str, typing.Any])¶ Get the Python positional and keyword arguments.
This may be over-ridden by subclasses.
Class methods
-
classmethod
invoke
()¶ Invoke a particular callback function instance.
This is invoked from the “Vim World” by VPE_Call. The global Vim dictionary variable _vpe_args_ will have been set up to contain ‘uid’ and ‘args’ entries. The ‘uid’ is used to find the actual
Callback
instance and the ‘args’ is a sequence of Vim values, which are passed to the callback as positional areguments.
-
classmethod
on_del
(uid)¶ “Handle deletion of weak reference to method’s instance.