Detailling the C-API based code implementing the primary libedit interface.
The C-code has some documentation of its own (in comments) and has added basic docstrings for each item. Sphinx does not seem to be able to pull those out unfortunately.
-
class
editline._editline.
EditLineBase
(name: str, in_stream: object, out_stream: object, err_stream: object) → object¶ -
:module: editline._editline
Bases:
object
This is the base-interface class for binding to NetBSD’s libedit library. It implements a similar functionality as readline.so but using a different API. (It does have a readline API but that has been tried and beaten a lot in the readline extension to moderate avail. It has greatly over complicated that extension and really does not work too well…)
param name: A name of the instance param in_stream: A file-like object where the input is pulled param out_stream: A file-like object where the output is pushed param err_stream: A file-like object where the errors are pushed returns: EditLineBase class instance Each stream must implement the fileno() member function so that a C FILE handle can be opened and used based on that fileno.
-
H_ADD
cmd value for history() api to add a history command¶
-
H_APPEND
cmd value for history() api to append a history command¶
-
H_CURR
cmd value for history() api to get the current entry¶
-
H_DEL
cmd value for history() api to delete a history command¶
-
H_ENTER
cmd value for history() api to add a new history command¶
-
H_FIRST
cmd value for history() api to get the first history command¶
-
H_GETSIZE
cmd value for history() api to return the size of th history¶
-
H_GETUNIQUE
cmd value for history() api to only store unique commands¶
-
prompt
set the command-line prompt string (default '>>> ')¶
-
rprompt
set the command-line right-side prompt string¶
-
in_stream
terminal interface file-like object for `stdin`¶
-
out_stream
terminal interface file-like object for `stdout`¶
-
err_stream
terminal interface file-like object for `stderr`¶
-
_completer
(text: str) → list¶ Compute matching attributes to an object.
Parameters: text – the command-line text to be completed Returns: All available commands which have text as a prefix. Notes
This routine is, effectively, a Python callback from libedit’s completion coding from within the C-API. The goal is to do the bulk of the command “figuring-out” in Python where it is sooooo much easier to manage lists of strings.
Warning
This routine is a default and must be overidden in a subclass.
-
delete_text
(count: int)¶ Scrub out count characters of the command-line at the current position
Parameters: count – count of characters to be removed Returns: Nothing
-
insert_text
(text: str)¶ Insert some additional text onto the command line at the current position.
Parameters: text – the text string to be inserted into the current command-line Returns: Nothing
-
readline
() → str¶ Engage the user interactively in a tab-completion enable input.
Returns: string input by user
-
redisplay
()¶ Force the terminal library to re-draw the current command-line.
Returns: Nothing
-
history
(cmd: int, *args)¶ Direct interface to libedit’s history API.
Parameters: - cmd – an H_ constant from the class
- args – arguments vary based on the cmd
Returns: Varies based on the cmd
Notes
The details for arguments pertaining to each H_ command value are best documented in libedit’s history.3 man-page.
-
read_history_file
(read_history_file: str) → int¶ Load the given filename into the history buffer. The format of this file is defined by libedit itself and is best generated with write_history_file().
Parameters: fname – filename of the file to load into history Returns: Error code on failure or 0 on success
-
write_history_file
(write_history_file: str) → int¶ Write out the accumulated history of commands input in this instance to a file of the given name.
Parameters: fname – filename of the file to write Returns: Error code on failure or 0 on success
The general implementation of this module contains two aspects:
- EditLineBase class for instances of interpreters
- Module global initializations for system interface (python -i)
In order to engage the terminal completion using editline, it is necessary for it to be loaded and setup with a lineeditor instance. The EditLineBase subclass provides the more specific support for Python’s interpreter (or a custom one if you build it) and works with lineeditor to provide the fancier functionality of the tab-completer. To configure the global instance, the code is:
-
from editline import _editline
from editline.editline import EditLine
from editline import lineeditor
editline_system = _editline.get_global_instance()
if editline_system is None:
sys_el = EditLine("PythonSystem", sys.stdin, sys.stdout, sys.stderr)
_editline.set_global_instance(sys_el)
sys_line_ed = lineeditor.EditlineCompleter(sys_el)
lineeditor.global_line_editor(sys_line_ed)
This code is implemented in the sitecustomize.py file distributed (and installed!) by this package.
Libedit works on a per-instance basis which is quite unlike libreadline’s mess of global variables. Likewise, the Python infrastructure for EditLine follows libedit’s lead.
To that end, the code above is:
- Creating the global instances of an EditLine and a Completer
- These are each registered with their respective modules so that other imports of the modules can gain access to those instances. This is more-or-less like doing import readline.
There are further details of how to weave the infrastructure into the Python interpreter’s mechanics. Have a look at sitecustomize.py for the gory details.
The mechanics which are not apparent from sitecustomize.py are the C-API bindings done in _editline.so.
A (global) callback is registered with the Python runtime which is called in interactive mode to engage the readline functionality. This routine is a C-function only, called
call_editline()
. Its interface is defined by the Python infrastructure and it depends on having a valid instance of an EditLineBase subclass initialized and registered before the terminal is used. Hence the code in sitecustomize.py. This is emulated from the readline implementation.