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!
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.
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
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
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 commmand|
||Backwards history search|
||SIGSTOP current job|
||SIGINT current job|
There are a few useful
prompt_toolkit tools that will help us create better
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
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): handler = bindings.registry.add_binding @handler(Keys.ControlW) def say_hi(event): event.current_buffer.insert_text('hi')
Put that in your xonshrc, restart xonsh and then see if
Ctrl-w does anything (it should!)
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
-l in the current directory:
@handler(Keys.ControlP) def run_ls(event): ls -l event.cli.renderer.erase()
event.cli.renderer.erase() is required to redraw the prompt
after asking for a separate command to send information to
Restrict actions with filters¶
Often we want a key command to only work if certain conditions are met. For
<TAB> key in xonsh brings up the completions menu, but then it
also cycles through the available completions. We use filters to create this
A few helpful filters are included with
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
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
Control L will list the
contents of your current directory if there are fewer than 10 items in it.
Useful? Debatable. Powerful? Yes.