Urwid Readline

0.15.1 · active · verified Wed Apr 15

Urwid Readline (urwid-readline) is a Python library that provides a textbox edit widget for the Urwid console UI library, enhancing it with familiar readline-like keyboard shortcuts. Currently at version 0.15.1, the library maintains a stable release cadence as a specialized widget for Urwid applications.

Warnings

breaking urwid-readline is built on top of the Urwid library. Breaking changes in Urwid (e.g., in versions 3.0.0 and 4.0.0) may affect urwid-readline applications. Always check the Urwid changelog when upgrading your Urwid dependency.
Fix: Refer to the Urwid library's official documentation and changelog for specific migration steps. Ensure your Urwid dependency is compatible with your urwid-readline version and application code.
gotcha When using `urwid-readline` with Python 3.14, older versions of the underlying `urwid` library might experience buffer overflow and unpacking errors related to terminal size detection. This was a known issue in `urwid`.
Fix: Upgrade your `urwid` dependency to at least version 3.0.5 or newer to ensure compatibility and stability with Python 3.14+ environments.
gotcha Direct manipulation of Urwid widgets (e.g., for updating text or displaying alarms) can sometimes be non-intuitive and lead to unexpected behavior if not handled within the `urwid.MainLoop` context or by correctly managing widget states. This can be a source of frustration for new users.
Fix: Ensure all UI updates are performed through the `urwid.MainLoop`'s event handling or `set_alarm` mechanism. For dynamic content, use `urwid.Text` or `urwid.Edit` widgets' `set_text` method appropriately. Consult the main Urwid documentation for best practices in updating display elements.

Install

pip install urwid-readline Install stable version

Imports

ReadlineEdit
```
from urwid_readline import ReadlineEdit
```

Quickstart

This quickstart creates a simple Urwid application with a `ReadlineEdit` widget. It demonstrates basic input, modifying the widget's text on 'enter', and exiting the application by pressing 'q'. This provides a minimal but functional example of integrating `urwid-readline` into an Urwid application.

import urwid
from urwid_readline import ReadlineEdit

class MyReadlineEdit(ReadlineEdit):
    def keypress(self, size, key):
        if key == 'enter':
            # When 'enter' is pressed, update the widget's text
            self.set_edit_text(f'You typed: {self.edit_text}')
            return None # Indicate that the key was handled
        return super().keypress(size, key)


def exit_on_q(key):
    if key in ('q', 'Q'):
        raise urwid.ExitMainLoop()

# Create an instance of our custom ReadlineEdit
edit = MyReadlineEdit(edit_text='Hello, Urwid Readline!', multiline=True)

# Wrap the edit widget in a Filler to allow it to expand
fill = urwid.Filler(edit, 'top')

# Set up the main loop with our fill widget and a handler for unhandled input
loop = urwid.MainLoop(fill, unhandled_input=exit_on_q)

# Run the Urwid application
loop.run()

view raw JSON →