editline package

Submodules

editline.editline module

editline._editline module

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:

EditLine Bootstrap
  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.

editline.lineeditor module

Module contents

Track versioning.

editline.version()[source]

Return the version number of this module.

Parameters:None –
Returns:String containing the major, minor, micro version number.