0
# GNU Readline
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: gnureadline
7
- **Language**: Python (C extension)
8
- **Installation**: `pip install gnureadline`
9
- **Compatibility**: Python 2.6, 2.7, 3.2-3.13 (POSIX platforms, excluding Windows)
10

11
## Core Imports
12

13
Direct import (recommended):
14

15
```python
16
import gnureadline
17
```
18

19
Conditional import pattern:
20

21
```python
22
try:
23
    import gnureadline as readline
24
except ImportError:
25
    import readline
26
```
27

28
Alternative module import (for systems without builtin readline):
29

30
```python
31
import readline  # Falls back to gnureadline via provided readline.py
32
```
33

34
## Basic Usage
35

36
```python
37
import gnureadline
38

39
# Basic line editing with history
40
gnureadline.add_history("first command")
41
gnureadline.add_history("second command")
42

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

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

55
gnureadline.set_completer(complete_function)
56
gnureadline.parse_and_bind("tab: complete")
57

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

63
## Architecture
64

65
The gnureadline package consists of three main components:
66

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

71
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.
72

73
## System Integration
74

75
Install readline override for interactive Python shell:
76

77
```bash
78
# Install override for current Python interpreter
79
python -m override_readline
80

81
# Install with site-wide preference (bypasses user site)
82
python -s -m override_readline
83
```
84

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

87
## Capabilities
88

89
### Command Line Editing
90

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

93
```python { .api }
94
def parse_and_bind(string: str):
95
    """Execute the init line provided in the string argument."""
96

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

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

103
def redisplay():
104
    """Force redisplay of the current line."""
105
```
106

107
[Command Line Editing](./line-editing.md)
108

109
### History Management  
110

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

113
```python { .api }
114
def add_history(line: str):
115
    """Add a line to the history buffer."""
116

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

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

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

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

129
def write_history_file(filename: str = None):
130
    """Save the history to a file."""
131
```
132

133
[History Management](./history.md)
134

135
### Tab Completion
136

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

139
```python { .api }
140
def set_completer(function):
141
    """Set the completion function."""
142

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

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

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

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

155
def get_endidx() -> int:
156
    """Get the ending index of the completion."""
157
```
158

159
[Tab Completion](./completion.md)
160

161
### Hook Functions
162

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

165
```python { .api }
166
def set_completion_display_matches_hook(function):
167
    """Set hook for displaying completion matches."""
168

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

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

176
[Hook Functions](./hooks.md)
177

178
### Utilities
179

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

182
```python { .api }
183
# readline.py - Pure Python wrapper
184
from gnureadline import *
185

186
# override_readline.py - System integration
187
def main() -> int:
188
    """Main entry point for override installation."""
189
```
190

191
[Utilities](./utilities.md)
192

193
## Error Handling
194

195
The gnureadline module raises standard Python exceptions:
196

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

202
History indexing behavior:
203
- `get_history_item()` uses 1-based indexing (index 0 returns None)
204
- `remove_history_item()` and `replace_history_item()` use 0-based indexing
205
- This matches GNU Readline's API behavior for compatibility