Module vpe.channels

Pythonic wrappers for Vim’s channels.

Channel

class channels.Channel(...)

Channel(
        net_address: str,
        drop: Optional[str] = None,
        noblock: Optional[bool] = None,
        waittime: Optional[int] = None,

Pythonic wrapper around a Vim channel.

Parameters

net_address

A network address of the form hostname:port.

drop

When to drop messages. Must be ‘auto’ or ‘never’.

noblock

Set to true to prevent blocking on on write operations.

waittime

Time to wait for a connection to succeed.

timeout_ms

Time to wait for blocking request.

Attributes

open

True if the channel is currently open.

vch: VimChannel:

The underlying VimChannel object.

Properties

property is_open → bool

Test whether the channel is open.

Methods

close() → None

Close the channel.

Related vim function = ch_close.

close_in() → None

Close the input part of the channel.

Related vim function = ch_info.

connect()

If necessary, try to connect.

getbufnr(what: str) → int

Get the number of the buffer thas is being used for what.

Related vim function = ch_getbufnr.

Parameters

what: str

The type of use. One of ‘err’, ‘out’ or an empty string.

info() → dict

Get information about the channel.

Related vim function = ch_info.

Return value

A dictionary of information.

log(msg: str) → None

Write a message to the channel log file (if open).

Related vim function = ch_log. Note that this always provides the channel argument.

Parameters

msg: str

The message to add to the log file.

on_close()

Handler for when channel is closed.

Not invoked when the close method is used.

Needs to be over-ridden in a subclass.

on_connect()

Handler for a new outgoing connection.

May be over-ridden in a subclass.

on_message(message: str)

Handler for messages not explicitly handled by read methods.

Needs to be over-ridden in a subclass.

The contents of message depend on the type of the channel. Note that for a raw channel, this is invoked when any amount of the input data stream has been received. It is up to the application code to buffer and decode the stream’s contents.

Parameters

message: str

The received message. This is always a string, even for raw channels. Vim replaces any NUL characters with newlines, so pure binary messages cannot be handled using on_message.

read(timeout_ms: int | None = None)

Read any available input.

send(message: str | bytes) → None

Send a message to the server.

Related vim function = ch_sendraw.

Parameters

message: Union

The message to send to the server. A bytes value is converted to a Latin-1 string before sending.

settimeout(timeout_ms: int | None = None)

Set the default timeout for the channel.

Related vim function = ch_setoptions.

Parameters

timeout_ms: Optional

Time to wait for blocking request.

status(part: str | None = None) → str

Get information about the channel.

Related vim function = ch_status.

Parameters

part: Optional

Which part of the channel to query; ‘err’ or ‘out’.

Return value

One of the strings ‘fail’, ‘open’, ‘buffered’ or ‘closed’.

JSChannel

class channels.JSChannel(...)

JSChannel(
        net_address: str,
        drop: Optional[str] = None,
        noblock: Optional[bool] = None,
        waittime: Optional[int] = None,

Pythonic wrapper around a Vim channel in JavaScript mode.

JsonChannel

class channels.JsonChannel(...)

JsonChannel(
        net_address: str,
        drop: Optional[str] = None,
        noblock: Optional[bool] = None,
        waittime: Optional[int] = None,

Pythonic wrapper around a Vim channel in JSON mode.

NLChannel

class channels.NLChannel(...)

NLChannel(
        net_address: str,
        drop: Optional[str] = None,
        noblock: Optional[bool] = None,
        waittime: Optional[int] = None,

Pythonic wrapper for a newline based channel.

RawChannel

class channels.RawChannel(...)

RawChannel(
        net_address: str,
        drop: Optional[str] = None,
        noblock: Optional[bool] = None,
        waittime: Optional[int] = None,

Pythonic wrapper for a raw channel.

SyncChannel

class channels.SyncChannel(...)

SyncChannel(
        net_address: str,
        drop: Optional[str] = None,
        noblock: Optional[bool] = None,
        waittime: Optional[int] = None,

Pythonic wrapper around a “json” or “js” channel.

Methods

evalexpr(expr: Any, timeout_ms: int | None = None) → Any

Evaluate an expression on the server.

Related vim function = ch_evalexpr.

Parameters

expr: Any

The expression to send to the server for evaluation.

timeout_ms: Optional

Max time to wait for a response. This overrides the timeout_ms given at construction time.

sendexpr(...)

sendexpr(
        expr: Union[None, int, float, str, bool, List[Any], Dict[str, Any]]

Send an expression to the server.

Related vim function = ch_sendexpr.

Parameters

expr: Union

The expression to send to the server.

VimChannel

class channels.VimChannel(varname: str)

Simple proxy for a Channel.

This manages keeping the underlying Vim channel object alive, by storing it in a global Vim variable.

Parameters

varname

The name of the vim variable currently referencing the Channel.

Attributes

varname

The name of a Vim variable holding a reference to the underlying Vim channel object. This is provided for debugging purposes.

Properties

property chid

The ID for this channel.

property closed

True of the channel could not be opened or has been closed.

property info

Get the information for a channel.

Methods

close()

Mark as closed and release the underlying reference variable.