Urwid Library

Warnings

• breaking Version 4.0.0 removed several public and protected methods that were previously deprecated. Examples include `Filler.get_body()`, `Filler.set_body()`, and various methods from `Canvas` and `AttrSpec`.
  Fix: Review upgrade notes for `urwid` 4.0.0 and replace calls to removed methods with their non-deprecated equivalents or current API patterns. If possible, update code to use direct attribute access or new helper functions.
• breaking Version 3.0.0 removed several legacy widgets and properties, including `FlowWidget`, `BoxWidget`, `FixedWidget`, and the `__super` property. Code relying on these will fail.
  Fix: Migrate existing code using these deprecated components to modern `urwid` widget classes and composition patterns. Refer to `urwid` documentation for alternatives.
• gotcha Windows support for `urwid` is primarily for Windows 10+ and relies on the default console host (conhost). There may be visual quirks, performance issues, or incomplete feature support (e.g., mouse events) compared to Linux/macOS terminals.
  Fix: Test `urwid` applications thoroughly on target Windows environments. Consider using WSL2 for a more consistent terminal experience if extensive `urwid` features are required on Windows.
• gotcha While `user_arg` for `urwid.connect_signal` was briefly deprecated (v3.0.4) and then un-deprecated (v3.0.5), it can still lead to confusion. The `user_args` parameter (as a tuple) is generally preferred for passing multiple arguments or for consistency with other callback patterns.
  Fix: For new code, prefer `user_args=(arg1, arg2)` when connecting signals. For existing code, `user_arg` should continue to function in 3.0.5+ but be aware of its history if encountering warnings in older 3.x versions.
• gotcha Urwid's main loop typically captures all input, including mouse events and keyboard input. This can make debugging or external interaction with the terminal challenging. Ensure your `unhandled_input` handler or event filtering is robust.
  Fix: Design your `unhandled_input` function carefully to handle unexpected keys or provide an escape mechanism. For debugging, consider redirecting output or using an external debugger that can attach to the process without interfering with `urwid`'s input loop.

Install

• pip install urwid Install Urwid

Imports

• urwid

  import urwid

• Text

  import urwid
  urwid.Text(...)

• MainLoop

  import urwid
  urwid.MainLoop(...)

• Button

  import urwid
  urwid.Button(...)

Quickstart

This quickstart initializes a basic Urwid application displaying text and a button. Clicking the button updates the display with a message, and pressing 'Q' at any point exits the application. It demonstrates key concepts like widgets (Text, Button, Pile, Filler), event handling (connect_signal), and the main event loop (MainLoop).

import urwid

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

def show_message(button):
    response = urwid.Text([u"You clicked the button! ", ('bold', u"Press Q to quit.")])
    done = urwid.Button(u'Ok')
    urwid.connect_signal(done, 'click', exit_program)
    top_frame = urwid.Frame(
        header=urwid.Text("Message"),
        body=urwid.Filler(urwid.Pile([response, done]), 'top'),
        footer=None
    )
    loop.widget = top_frame # Replace current widget with message

def exit_program(button):
    raise urwid.ExitMainLoop()

# Create a text widget
text_widget = urwid.Text(u"Hello, Urwid! Press Space to click, Q to quit.")

# Create a button
button = urwid.Button(u'Click me!')
urwid.connect_signal(button, 'click', show_message)

# Arrange widgets in a pile, then fill the screen
pile = urwid.Pile([
    urwid.Text("Welcome to Urwid"),
    urwid.Divider(),
    text_widget,
    urwid.AttrMap(button, None, focus_map='reversed') # Add focus highlight
])
filler = urwid.Filler(pile, 'top')

# Create the main loop
loop = urwid.MainLoop(filler, unhandled_input=exit_on_q)
loop.run()