List Walker Classes

ListWalker

class urwid.ListWalker

Base class for objects that supply widgets to a ListBox on demand, by position.

get_focus() → tuple[_V_co, _K] | tuple[None, None]

Return the (widget, position) currently in focus.

This default implementation relies on a focus attribute and a __getitem__() method defined in a subclass.

Override and don’t call this method if these are not defined.

Returns:

(widget, position) or (None, None)

get_next(position: _K) → tuple[_V_co, _K] | tuple[None, None]

Return the (widget, position) after position.

This default implementation relies on a next_position() method and a __getitem__() method defined in a subclass.

Override and don’t call this method if these are not defined.

Parameters:

position – position to start from

Returns:

(widget, position) or (None, None)

get_prev(position: _K) → tuple[_V_co, _K] | tuple[None, None]

Return the (widget, position) before position.

This default implementation relies on a prev_position() method and a __getitem__() method defined in a subclass.

Override and don’t call this method if these are not defined.

Parameters:

position – position to start from

Returns:

(widget, position) or (None, None)

List-like List Walkers

class urwid.SimpleFocusListWalker(contents: Iterable[_T], wrap_around: bool = False)

ListWalker like SimpleListWalker that also keeps focus tracking items across edits.

Initialize a list walker, which can be treated as a list since it inherits MonitoredList.

Changes made to this object (when it is treated as a list) are detected automatically and will cause ListBox objects using this list walker to be updated.

Also, items added or removed before the widget in focus with normal list methods will cause the focus to be updated intelligently.

Parameters:

• contents – list to copy into this object

• wrap_around – if true, jumps to beginning/end of list on move

Raises:

ListWalkerError – contents is not iterable.

next_position(position: SupportsIndex) → int

Return position after position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no next position and wrap_around is false

positions(reverse: bool = False) → Iterable[int]

Return an iterable of positions. Optional method.

Parameters:

reverse – if true, return positions in reverse order

prev_position(position: SupportsIndex) → int

Return position before position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no previous position and wrap_around is false

set_focus(position: int) → None

Set focus position.

Parameters:

position – position to focus

set_modified_callback(callback: Any) → NoReturn

Raise NotImplementedError: this function inherited from MonitoredList is not implemented here.

Use connect_signal(list_walker, "modified", ...) instead.

Raises:

NotImplementedError – always

class urwid.SimpleListWalker(contents: Iterable[_T], wrap_around: bool = False)

ListWalker that presents a plain list of widgets, addressed by integer position.

Initialize a list walker, which can be treated as a list since it inherits MonitoredList.

Changes made to this object (when it is treated as a list) are detected automatically and will cause ListBox objects using this list walker to be updated.

Parameters:

• contents – list to copy into this object

• wrap_around – if true, jumps to beginning/end of list on move

Raises:

ListWalkerError – contents is not iterable.

property contents: Self

Return self.

Provides compatibility with old SimpleListWalker class.

next_position(position: int) → int

Return position after position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no next position and wrap_around is false

positions(reverse: bool = False) → Iterable[int]

Return an iterable of positions. Optional method.

Parameters:

reverse – if true, return positions in reverse order

prev_position(position: int) → int

Return position before position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no previous position and wrap_around is false

set_focus(position: int) → None

Set focus position.

Parameters:

position – position to focus

Raises:

IndexError – if there is no widget at position

set_modified_callback(callback: Callable[[], Any]) → NoReturn

Raise NotImplementedError: this function inherited from MonitoredList is not implemented here.

Use connect_signal(list_walker, "modified", ...) instead.

Raises:

NotImplementedError – always

Deque-like List Walkers

class urwid.SimpleFocusDequeWalker(contents: Iterable[_T], wrap_around: bool = False, maxlen: int | None = None)

A ListWalker backed by a MonitoredFocusDeque.

Mirrors SimpleFocusListWalker method-for-method, adapted to deque’s narrower API. See the performance caveat documented on SimpleDequeWalker – it applies equally here.

Build the walker, wrapping contents in a focus-tracking deque.

This class inherits MonitoredFocusDeque, which means it can be treated as a deque.

Changes made to this object (when it is treated as a deque) are detected automatically and will cause ListBox objects using this list walker to be updated.

Also, items added or removed before the widget in focus with normal deque methods – including eviction caused by maxlen – will cause the focus to be updated intelligently.

Parameters:

• contents – iterable to copy into this object

• wrap_around – if true, jumps to beginning/end of deque on move

• maxlen – if set, bounds the deque’s length; the oldest items are silently evicted from the opposite end once full, and focus is adjusted to keep tracking a sensible item (see MonitoredFocusDeque)

Raises:

ListWalkerError – contents is not iterable.

next_position(position: SupportsIndex) → int

Return position after position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no next position and wrap_around is false

positions(reverse: bool = False) → Iterable[int]

Return an iterable of positions. Optional method.

Parameters:

reverse – if true, return positions in reverse order

prev_position(position: SupportsIndex) → int

Return position before position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no previous position and wrap_around is false

set_focus(position: int) → None

Set focus position.

Parameters:

position – position to focus

set_modified_callback(callback: Any) → NoReturn

Raise NotImplementedError: this function inherited from MonitoredFocusDeque is not implemented here.

Use connect_signal(list_walker, "modified", ...) instead.

Raises:

NotImplementedError – always

class urwid.SimpleDequeWalker(contents: Iterable[_T], wrap_around: bool = False, maxlen: int | None = None)

A ListWalker backed by a MonitoredDeque.

Mirrors SimpleListWalker method-for-method, adapted to deque’s narrower API (in particular, maxlen-bounded eviction).

Note

ListWalker.get_focus()/ListWalker.get_next()/ListWalker.get_prev() (inherited, unmodified) index via self[position], and deque.__getitem__ is O(n) (linked-block structure) rather than a list’s O(1) – worth bearing in mind for a very large unbounded deque, though the bounded/maxlen scrollback use case this class targets is small enough that it does not matter in practice. No caching layer is provided.

Initialize a deque walker, which can be treated as a deque since it inherits MonitoredDeque.

Changes made to this object (when it is treated as a deque) are detected automatically and will cause ListBox objects using this list walker to be updated.

Parameters:

• contents – iterable to copy into this object

• wrap_around – if true, jumps to beginning/end of deque on move

• maxlen – if set, bounds the deque’s length; the oldest items are silently evicted from the opposite end once full

Raises:

ListWalkerError – contents is not iterable.

property contents: SimpleDequeWalker[_T]

Return self.

Provides compatibility with old SimpleListWalker class.

next_position(position: int) → int

Return position after position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no next position and wrap_around is false

positions(reverse: bool = False) → Iterable[int]

Return an iterable of positions. Optional method.

Parameters:

reverse – if true, return positions in reverse order

prev_position(position: int) → int

Return position before position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no previous position and wrap_around is false

set_focus(position: int) → None

Set focus position.

Parameters:

position – position to focus

Raises:

IndexError – if there is no widget at position

set_modified_callback(callback: Callable[[], Any]) → NoReturn

Raise NotImplementedError: this function inherited from MonitoredDeque is not implemented here.

Use connect_signal(list_walker, "modified", ...) instead.

Raises:

NotImplementedError – always

TreeWalker and Nodes

class urwid.TreeWalker(start_from: TreeNode[Any])

ListWalker-compatible class for displaying TreeWidgets.

positions are TreeNodes.

start_from: TreeNode with the initial focus.

get_focus() → tuple[TreeWidget[TreeNode[Any]], TreeNode[Any]]

Return the widget and node currently in focus.

get_next(start_from: TreeNode[Any]) → tuple[TreeWidget[TreeNode[Any]], TreeNode[Any]] | tuple[None, None]

Return the widget and node that follow start_from depth first, or (None, None).

get_prev(start_from: TreeNode[Any]) → tuple[TreeWidget[TreeNode[Any]], TreeNode[Any]] | tuple[None, None]

Return the widget and node that precede start_from depth first, or (None, None).

set_focus(focus: TreeNode[Any]) → None

Set the node in focus and notify listeners that the walker was modified.

class urwid.TreeNode(value: _T, parent: ParentNode[Any] | None = None, key: Hashable = None, depth: int | None = None)

Store tree contents and cache TreeWidget objects.

A TreeNode consists of the following elements: * key: accessor token for parent nodes * value: subclass-specific data * parent: a TreeNode which contains a pointer back to this object * widget: The widget used to render the object

Store value under key, with parent and depth as given, or computed from parent when omitted.

change_key(key: Hashable) → None

Rename this node to key, updating the parent’s reference to it as well.

get_depth() → int

Return this node’s depth in the tree, computing and caching it if necessary.

get_index() → int | None

Return this node’s position among its parent’s children, or None for the root.

get_key() → Hashable

Return this node’s key.

get_parent() → ParentNode[Any]

Return this node’s parent, loading it with load_parent() if necessary.

get_root() → ParentNode[Any]

Return the root node of the tree this node belongs to.

get_value() → _T

Return this node’s value.

get_widget(reload: bool = False) → TreeWidget[Self]

Return the widget for this node.

is_root() → bool

Return whether this node is the root of the tree.

load_parent() → ParentNode[Any]

Provide TreeNode with a parent for the current node.

This function is only required if the tree was instantiated from a child node (virtual function)

Raises:

TreeWidgetError – the subclass does not override this method.

load_widget() → TreeWidget[Self]

Create the widget for this node.

next_sibling() → TreeNode[Any] | None

Return the next sibling of this node, or None if there is none.

prev_sibling() → TreeNode[Any] | None

Return the previous sibling of this node, or None if there is none.

set_key(key: Hashable) → None

Set this node’s key without updating the parent’s reference to it.

class urwid.ParentNode(value: Any, parent: ParentNode[Any] | None = None, key: Hashable = None, depth: int | None = None)

Maintain sort order for TreeNodes.

Store value under key, with no child keys loaded yet.

change_child_key(oldkey: Hashable, newkey: Hashable) → None

Rename a child, moving it from oldkey to newkey.

Raises:

TreeWidgetError – newkey is already used by another child.

get_child_index(key: Hashable) → int

Return the position of the child key among the child keys.

Raises:

TreeWidgetError – key is not a child of this node.

get_child_keys(reload: bool = False) → Sequence[Hashable]

Return a possibly ordered list of child keys.

get_child_node(key: Hashable, reload: bool = False) → TreeNode[Any]

Return the child node for a given key. Create if necessary.

get_child_widget(key: Hashable) → TreeWidget[TreeNode[Any]]

Return the widget for a given key. Create if necessary.

get_first_child() → TreeNode[Any]

Return the first TreeNode in the directory.

get_last_child() → TreeNode[Any]

Return the last TreeNode in the directory.

has_children() → bool

Return whether this node has any children.

load_child_keys() → Sequence[Hashable]

Provide ParentNode with an ordered list of child keys (virtual function).

Raises:

TreeWidgetError – the subclass does not override this method.

load_child_node(key: Hashable) → TreeNode[Any]

Load the child node for a given key (virtual function).

Raises:

TreeWidgetError – the subclass does not override this method.

next_child(key: Hashable) → TreeNode[Any] | None

Return the next child node in index order from the given key.

prev_child(key: Hashable) → TreeNode[Any] | None

Return the previous child node in index order from the given key.

set_child_node(key: Hashable, node: TreeNode[Any]) → None

Set the child node for a given key.

Useful for bottom-up, lazy population of a tree.