Python readline interface focusing on completion
Project description
Introduction
The rl package aims to provide a full implementation of the GNU Readline Custom Completer interface.
Package Contents
rl exports the following components:
- completer
Interface to the readline completer. Used to configure the completion aspects of readline.
- completion
Interface to the active readline completion. Used to interact with readline when a completion is in progress.
- generator
A factory turning any callable into a completion entry function that can be handed to readline.
- print_exc
A decorator printing exceptions to stderr. Useful when writing Python completions and hooks, as exceptions occurring there are usually swallowed by the in-between C code.
- history
Interface to the readline history. Used to read and write history files and to manipulate history entries.
- readline
The readline interface module. Contains everything known from the standard library plus extensions specific to the rl package. The completer, completion, and history interfaces make use of this module, and you should rarely need to interact with it directly.
For further details, please refer to the API Documentation.
Example Code
The code below implements system command completion similar to bash:
import os
from rl import completer
from rl import generator
def complete(text):
# Return executables matching 'text'
for dir in os.environ.get('PATH').split(':'):
dir = os.path.expanduser(dir)
if os.path.isdir(dir):
for name in os.listdir(dir):
if name.startswith(text):
if os.access(os.path.join(dir, name), os.R_OK|os.X_OK):
yield name
def main():
# Set the completion function
completer.completer = generator(complete)
# Enable TAB completion
completer.parse_and_bind('tab: complete')
command = raw_input('command: ')
print 'You typed:', command
More elaborate examples can be found here and in the gpgkeys package.
Repository Access
rl development is hosted on github.
Installation
rl has been tested with GNU Readline versions 5 and 6.
On Linux, install libreadline5-dev (or equivalent) before attempting to build rl. On Mac OS X, you need a Python built with MacPorts or Fink, as the system Python is linked to the BSD editline library and not GNU readline.
rl requires distribute >= 0.6.6. If you have not upgraded your setuptools yet, type:
/path/to/easy_install distribute
Then type:
/path/to/easy_install rl
and watch the console. When it reads:
Finished processing dependencies for rl
you are done and rl is ready to use.
Changelog
1.0a7 - 2009-11-05
Rename _readline module to readline since it’s not private. [stefan]
Remove dump and read_key APIs from public interfaces. [stefan]
1.0a6 - 2009-10-30
Unclutter the completer interface by removing settings that can just as well be made with parse_and_bind. [stefan]
Fix a memory leak in username_completion_function and filename_completion_function. [stefan]
Add a custom epydoc stylesheet to make its reST rendering more pleasant. [stefan]
1.0a5 - 2009-10-29
Make all completion properties writable. While not useful in production, this allows us to write better tests. [stefan]
Improve API documentation and add a call graph for the completion process. This goes a long way in explaining how readline completion works. [stefan]
1.0a4 - 2009-10-27
Implement the generator factory using an iterator instead of a list. [stefan]
Remove find_completion_word so people don’t get ideas. [stefan]
Don’t list distribute as dependency, setuptools will do the right thing. [stefan]
1.0a3 - 2009-10-22
Add __slots__ to interface objects to make them immutable. [stefan]
Support Python 2.5, 2.6, and 3.1 (thanks to distribute). [stefan]
Approach something like test coverage. [stefan]
1.0a2 - 2009-10-08
Make the generator factory work for all types of callables. [stefan]
Improve examples. [stefan]
1.0a1 - 2009-10-04
Initial release.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
