Usage

The purpose of readline is to improve the interactive experience with the python interpreter by improving the line editing facilities. The most important being tab completion and copy and paste.

Configuration file

The configuration file is read from the users home directory and is named pyreadlineconfig.ini. The files syntax is not the same as for GNU readline but a python syntax is used instead. The available commands are:

bind_exit_key

is used to bind the keys that are used to exit the interpreter. (Ctrl-d, ctrl-z)

bind_key

is used to bind keys to editor functions

un_bind_key

is used to unbind keys can be useful to unbind default bindings the user does not like

bell_style

is used to set bell style. (none|visible|audible)

show_all_if_ambiguous

is used to enable the showing of a list of all alternative for tab completion (on|off)

mark_directories

show directories (on|off)

completer_delims

Which delimeters should be used to separate words for tab completion

debug_output

Turn on debug output (on|off). Not implemented yet.

disable_readline

Disable pyreadline completely (True|False).

allow_ctrl_c

Allows use of ctrl-c as copy key, still propagate keyboardinterrupt when not waiting for input.

ctrl_c_tap_time_interval

Set the ctrl-c double tap time interval to be used before issuing a KeyboadInterupt. Used to be able to have ctrl-c bound to copy.

history_filename

Set name of history file. Default is %USERPROFILE%/.pythonhistory

history_length

Set max length of history file default 200

Here is the example config file shipped with pyreadline:

#Bind keys for exit (keys only work on empty lines
#disable_readline(True)		#Disable pyreadline completely.
from __future__ import print_function, unicode_literals, absolute_import
debug_output("off")             #"on" saves log info to./pyreadline_debug_log.txt
                                #"on_nologfile" only enables print warning messages
bind_exit_key("Control-d")
bind_exit_key("Control-z")

#Commands for moving	
bind_key("Home",                "beginning_of_line")
bind_key("End",                 "end_of_line")
bind_key("Left",                "backward_char")
bind_key("Control-b",           "backward_char")
bind_key("Right",               "forward_char")
bind_key("Control-f",           "forward_char")
bind_key("Alt-f",               "forward_word")
bind_key("Alt-b",               "backward_word")
bind_key("Clear",               "clear_screen")
bind_key("Control-l",           "clear_screen")
bind_key("Control-a",           "beginning_of_line")
bind_key("Control-e",           "end_of_line")
#bind_key("Control-l",          "redraw_current_line")

#Commands for Manipulating the History
bind_key("Return",              "accept_line")
bind_key("Control-p",           "previous_history")
bind_key("Control-n",           "next_history")
bind_key("Up",                  "history_search_backward")
bind_key("Down",                "history_search_forward")
bind_key("Alt-<",               "beginning_of_history")
bind_key("Alt->",               "end_of_history")
bind_key("Control-r",           "reverse_search_history")
bind_key("Control-s",           "forward_search_history")
bind_key("Alt-p",               "non_incremental_reverse_search_history")
bind_key("Alt-n",               "non_incremental_forward_search_history")

bind_key("Control-z",           "undo")
bind_key("Control-_",           "undo")

#Commands for Changing Text
bind_key("Delete",              "delete_char")
bind_key("Control-d",           "delete_char")
bind_key("BackSpace",           "backward_delete_char")
#bind_key("Control-Shift-v",    "quoted_insert")
bind_key("Control-space",       "self_insert")
bind_key("Control-BackSpace",   "backward_delete_word")

#Killing and Yanking
bind_key("Control-k",           "kill_line")
bind_key("Control-shift-k",     "kill_whole_line")
bind_key("Escape",              "kill_whole_line")
bind_key("Meta-d",              "kill_word")
bind_key("Control-w",           "unix_word_rubout")
#bind_key("Control-Delete",     "forward_kill_word")

#Copy paste
bind_key("Shift-Right",         "forward_char_extend_selection")
bind_key("Shift-Left",          "backward_char_extend_selection")
bind_key("Shift-Control-Right", "forward_word_extend_selection")
bind_key("Shift-Control-Left",  "backward_word_extend_selection")
bind_key("Control-m",           "set_mark")

bind_key("Control-Shift-x",     "copy_selection_to_clipboard")
#bind_key("Control-c",           "copy_selection_to_clipboard")  #Needs allow_ctrl_c(True) below to be uncommented
bind_key("Control-q",           "copy_region_to_clipboard")
bind_key('Control-Shift-v',     "paste_mulitline_code")
bind_key("Control-x",           "cut_selection_to_clipboard")

bind_key("Control-v",           "paste")
bind_key("Control-y",           "yank")
bind_key("Alt-v",               "ipython_paste")

#Unbinding keys:
#un_bind_key("Home")

#Other
bell_style("none") #modes: none, audible, visible(not implemented)
show_all_if_ambiguous("on")
mark_directories("on")
completer_delims(" \t\n\"\\'`@$><=;|&{(?")
complete_filesystem("off")
debug_output("off")
#allow_ctrl_c(True)  #(Allows use of ctrl-c as copy key, still propagate keyboardinterrupt when not waiting for input)

history_filename("~/.pythonhistory")
history_length(200) #value of -1 means no limit

#set_mode("vi")  #will cause following bind_keys to bind to vi mode as well as activate vi mode
#ctrl_c_tap_time_interval(0.3)

pyreadline with python interpreter

In your startup file (pointed to by environment variable PYTHONSTARTUP) add:

# -*- coding: UTF-8 -*-
# Example snippet to use in a PYTHONSTARTUP file
from __future__ import print_function, unicode_literals, absolute_import
try:
    import pyreadline.rlmain
    #pyreadline.rlmain.config_path=r"c:\xxx\pyreadlineconfig.ini"
    import readline, atexit
    import pyreadline.unicode_helper
    #
    #
    #Normally the codepage for pyreadline is set to be sys.stdout.encoding
    #if you need to change this uncomment the following line
    #pyreadline.unicode_helper.pyreadline_codepage="utf8"
except ImportError:
    print("Module readline not available.")
else:
    #import tab completion functionality
    import rlcompleter

    #Override completer from rlcompleter to disable automatic ( on callable
    completer_obj = rlcompleter.Completer()
    def nop(val, word):
        return word
    completer_obj._callable_postfix = nop
    readline.set_completer(completer_obj.complete)

    #activate tab completion
    readline.parse_and_bind("tab: complete")
    readline.read_history_file()
    atexit.register(readline.write_history_file)
    del readline, rlcompleter, atexit

This file is included in the doc directory of the distribution.

pyreadline with IronPython

THIS HAS NOT BEEN TESTED FOR A WHILE

Pyreadline can be used together with IronPython. Unfortunately the binary installs of IronPython can not run pyreadline directly. You need to patch the source code to make PythonCommandLine a public class that we can override.

• In PythonCommandLine.cs you need to change class PythonCommandLine to public class PythonCommandLine and recompile.
• Copy rlcompleter.py from a standard python install to your ironpython path (this file is not included with fepy).

pyreadline with IPython

In IPython pyreadline is automatically used if available.

Clipboard

Pyreadline can do copy/paste using the clipboard. Selections can be done using shift and arrowkeys as in most windows programs.

There are three different paste functions that can be bound.

paste

Paste windows clipboard. Assume single line strip other lines and end of line markers and trailing spaces

paste_mulitline_code

Paste windows clipboard as multiline code. Removes any empty lines in the code

ipython_paste

Paste windows clipboard. If enable_ipython_paste_list_of_lists is True then try to convert tabseparated data to repr of list of lists or repr of array. If enable_ipython_paste_for_paths==True then change \\ to / and spaces to \space.

International characters

The pyreadline package now supports international characters. However using international characters in the interactive prompt can be annoying on windows since the default codepage for the terminal is an ascii codepage (850 on swedish systems) but the filesystem often uses some other codepage (1252 on swedish systems). This means the filenames containing internationl characters entered on interactive prompt will not work. The workaround here is to change the codepage of your terminal to a more suitable one using the chcp command. For swedish systems chcp 1252 does the trick but you also have to change the terminal font to a font compatible with the wanted code page in the case of a swedish system that would be e.g. lucida console, or consolas using the properties dialog for the console.