Tutorial: prompt_toolkit custom keybindings

Are you really jonesing for some special keybindings? We can help you out with that. The first time is free and so is every other time!

Warning

This tutorial will let you hook directly into the prompt_toolkit keybinding manager. It will not stop you from rendering your prompt completely unusable, so tread lightly.

Overview

The prompt_toolkit shell has a registry for handling custom keybindings. You may not like the default keybindings in xonsh, or you may want to add a new key binding.

We’ll walk you though how to do this using prompt_toolkit tools to define keybindings and warn you about potential pitfalls.

All of the code below can be entered into your xonshrc

Control characters

We can’t and won’t stop you from doing what you want, but in the interest of a functioning shell, you probably shouldn’t mess with the following keystrokes. Some of them are ASCII control characters and really shouldn’t be used. The others are used by xonsh and will result in some loss of functionality (in less you take the time to rebind them elsewhere).

Keystroke	ASCII control representation	Default command
Control J	<Enter>	Run command
Control I	<Tab>	Indent, autocomplete
Control R		Backwards history search
Control Z		SIGSTOP current job
Control C		SIGINT current job

Useful imports

There are a few useful prompt_toolkit tools that will help us create better bindings:

from prompt_toolkit.keys import Keys
from prompt_toolkit.filters import Condition, EmacsInsertMode, ViInsertMode

Custom keyload function

We need our additional keybindings to load after the shell is initialized, so we define a function that contains all of the custom keybindings and decorate it with the appropriate event, in this case on_ptk_create.

We’ll start with a toy example that just inserts the text “hi” into the current line of the prompt:

@events.on_ptk_create
def custom_keybindings(bindings, **kw):

    @bindings.add(Keys.ControlW)
    def say_hi(event):
        event.current_buffer.insert_text('hi')

Put that in your xonshrc, restart xonsh and then see if pressing Ctrl-w does anything (it should!)

Note

It is also possible to write Keys.ControlW like c-w.

What commands can keybindings run?

Pretty much anything! Since we’re defining these commands after xonsh has started up, we can create keybinding events that run subprocess commands with hardly any effort at all. If we wanted to, say, have a command that runs ls -l in the current directory:

@handler(Keys.ControlP)
def run_ls(event):
    ls -l
    event.cli.renderer.erase()

Note

The event.cli.renderer.erase() is required to redraw the prompt after asking for a separate command to send information to STDOUT

Restrict actions with filters

Often we want a key command to only work if certain conditions are met. For instance, the <TAB> key in xonsh brings up the completions menu, but then it also cycles through the available completions. We use filters to create this behavior.

A few helpful filters are included with prompt_toolkit, like ViInsertMode and EmacsInsertMode, which return True when the respective insert mode is active.

But it’s also easy to create our own filters that take advantage of xonsh’s beautiful strangeness. Suppose we want a filter to restrict a given command to run only when there are fewer than ten files in a given directory. We just need a function that returns a Bool that matches that requirement and then we decorate it! And remember, those functions can be in xonsh-language, not just pure Python:

@Condition
def lt_ten_files(cli):
    return len(g`*`) < 10

Note

See the tutorial section on globbing for more globbing options.

Now that the condition is defined, we can pass it as a filter keyword to a keybinding definition:

@handler(Keys.ControlL, filter=lt_ten_files)
def ls_if_lt_ten(event):
    ls -l
    event.cli.renderer.erase()

With both of those in your .xonshrc, pressing Control L will list the contents of your current directory if there are fewer than 10 items in it. Useful? Debatable. Powerful? Yes.