or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

completion.mdhistory.mdhooks.mdindex.mdline-editing.mdutilities.md
tile.json

tessl/pypi-gnureadline

The standard Python readline extension statically linked against the GNU readline library.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/gnureadline@8.2.x

To install, run

npx @tessl/cli install tessl/pypi-gnureadline@8.2.0

index.mddocs/

GNU Readline

The standard Python readline extension statically linked against the GNU readline library. This package provides genuine GNU Readline functionality on platforms that ship with NetBSD's Editline (libedit) instead, particularly macOS. It enables proper command line editing, history management, and tab completion in Python interactive shells and applications.

Package Information

  • Package Name: gnureadline
  • Language: Python (C extension)
  • Installation: pip install gnureadline
  • Compatibility: Python 2.6, 2.7, 3.2-3.13 (POSIX platforms, excluding Windows)

Core Imports

Direct import (recommended):

import gnureadline

Conditional import pattern:

try:
    import gnureadline as readline
except ImportError:
    import readline

Alternative module import (for systems without builtin readline):

import readline  # Falls back to gnureadline via provided readline.py

Basic Usage

import gnureadline

# Basic line editing with history
gnureadline.add_history("first command")
gnureadline.add_history("second command")

# Get history items (1-based indexing)
first_item = gnureadline.get_history_item(1)  # "first command"
print(f"History length: {gnureadline.get_current_history_length()}")

# Set up tab completion
def complete_function(text, state):
    options = ['help', 'history', 'hello', 'world']
    matches = [opt for opt in options if opt.startswith(text)]
    if state < len(matches):
        return matches[state]
    return None

gnureadline.set_completer(complete_function)
gnureadline.parse_and_bind("tab: complete")

# Configure readline behavior
gnureadline.set_completer_delims(' \t\n`!@#$%^&*()=+[{]}\\|;:\'",<>?')
gnureadline.set_history_length(1000)

Architecture

The gnureadline package consists of three main components:

  • gnureadline (C extension): Core GNU Readline functionality with complete API compatibility
  • readline.py: Pure Python wrapper that imports all gnureadline functions (fallback for systems without builtin readline)
  • override_readline.py: Installation utility for system-wide readline replacement via site customization

The C extension is built from version-specific source files and statically links against the GNU readline library, providing full functionality without external dependencies beyond ncurses.

System Integration

Install readline override for interactive Python shell:

# Install override for current Python interpreter
python -m override_readline

# Install with site-wide preference (bypasses user site)
python -s -m override_readline

This installs code in Python's site customization that automatically replaces the system readline with gnureadline, enabling proper tab completion in the interactive shell.

Capabilities

Command Line Editing

Core line editing functionality for building interactive command-line applications with full GNU Readline support including configuration, buffer manipulation, and display control.

def parse_and_bind(string: str):
    """Execute the init line provided in the string argument."""

def get_line_buffer() -> str:
    """Get the current contents of the line buffer."""

def insert_text(string: str):
    """Insert text into the line buffer at the cursor position."""

def redisplay():
    """Force redisplay of the current line."""

Command Line Editing

History Management

Comprehensive history management with programmatic control over command history storage, retrieval, and persistence across sessions.

def add_history(line: str):
    """Add a line to the history buffer."""

def get_history_item(index: int) -> str:
    """Get history item by index (1-based)."""

def get_current_history_length() -> int:
    """Get the current number of history entries."""

def set_history_length(length: int):
    """Set maximum history length."""

def read_history_file(filename: str = None):
    """Load a readline history file."""

def write_history_file(filename: str = None):
    """Save the history to a file."""

History Management

Tab Completion

Programmable tab completion system with customizable word breaking and completion functions, supporting context-aware completion.

def set_completer(function):
    """Set the completion function."""

def get_completer():
    """Get the current completion function."""

def set_completer_delims(string: str):
    """Set the word break characters for completion."""

def get_completion_type() -> int:
    """Get the type of completion being attempted."""

def get_begidx() -> int:
    """Get the beginning index of the completion."""

def get_endidx() -> int:
    """Get the ending index of the completion."""

Tab Completion

Hook Functions

Callback system for customizing readline behavior at key points in the input process, enabling deep integration with readline's event system.

def set_completion_display_matches_hook(function):
    """Set hook for displaying completion matches."""

def set_startup_hook(function):
    """Set startup hook function called when readline is about to start."""

def set_pre_input_hook(function):
    """Set pre-input hook called after prompt is displayed, before input."""

Hook Functions

Utilities

Utility modules and scripts including system integration tools and alternative import mechanisms for different deployment scenarios.

# readline.py - Pure Python wrapper
from gnureadline import *

# override_readline.py - System integration
def main() -> int:
    """Main entry point for override installation."""

Utilities

Error Handling

The gnureadline module raises standard Python exceptions:

  • ImportError: Raised when gnureadline cannot be imported (typically on unsupported platforms)
  • OSError: Raised by file operations (read_history_file, write_history_file, append_history_file)
  • ValueError: Raised for invalid parameter values
  • IndexError: Raised when accessing history with invalid indexes

History indexing behavior:

  • get_history_item() uses 1-based indexing (index 0 returns None)
  • remove_history_item() and replace_history_item() use 0-based indexing
  • This matches GNU Readline's API behavior for compatibility