API

Layout

class modern_urwid.layout.Layout(xml_path: ~pathlib.Path, css_path: ~pathlib.Path | None = None, resources_cls=<class 'modern_urwid.layout.LayoutResourceHandler'>, xml_dir=None, css_dir=None)

Bases: object

Create a UI layout from XML and CSS.

This class is responsible for parsing XML and applying CSS styles to the created widgets. The root widget can be referenced with get_root().

get_palettes(): Get all palettes used in this layout.

get_root() → Widget: Get the root XML widget that can be rendered.

get_widget_by_id(id) → Widget | None: Get a widget by its id attribute.

load(): Parse the XML and CSS. Make sure to call register_widgets() first if neccessary.

on_enter(): Called when this is rendered on the mainloop with switch().

on_exit(): Called when this is removed from the mainloop with switch().

register_widgets(widgets: list[type[WidgetBuilder]]): Add custom widget builders for the XML parser. Note: do this before calling load().

style_widget(widget: Widget, classes=[], id=None) → AttrMap: Style a widget according to any given classes or id it may have.

class modern_urwid.layout.LayoutResourceHandler(layout: Layout, palettes=[], widgets: list[type[WidgetBuilder]] = [], css_variables: dict[str, str] = {})

Bases: ResourceHandler

A base class for extending a layout’s functionality.

Reference properties from the base class (e.g. callbacks) with the @ prefix. Reference properties from the data dictionary with brackets surrounding the key (e.g. "{user.name}").

get_css_variables() → dict[str, str]: Get custom CSS variables, used to override stylesheet variables.

get_palettes(): Get custom palettes.

get_resource(name): Get a custom resource (typically referenced by @ResourceName in XML).

get_widget_builder(tag: str) → type[WidgetBuilder] | None: Get a widget builder for a custom widget tag.

on_enter(): Called when the parent layout is rendered on the mainloop with switch().

on_exit(): Called when the parent layout is removed from the mainloop with switch().

on_load(): Called when loading the parent layout in register().

parse_resources_tag(element: Element): Parse the <mu:resources /> tag

parse_string_template(template): Parse a given string template, e.g. "User: {user.id}"

Layout Manager

class modern_urwid.layout_manager.LayoutManager(loop: MainLoop | None = None)

Bases: object

Manages multiple layouts and shared custom widgets and palettes between them.

get_loop() → MainLoop: Get the urwid MainLoop

register(name: str, layout: Layout): Register a new Layout

register_palette(palette): Register a set of palette entries in the urwid MainLoop.

register_widget(cls: type[WidgetBuilder] | None = None) → LambdaType

Register a custom widget builder.

This can be used either as a decorator (@manager.register_widget()) or by directly passing a class (manager.register_widget(MyCustomBuilder)).

run(): Run the urwid MainLoop

switch(name: str)

Switch to a different layout by name.

Calls the new layout’s on_enter() method, and the old layout’s on_exit() method.

Widget Builder

class modern_urwid.builder.WidgetBuilder(element: Element, children: list[Widget | WidgetContainerMixin] = [])

Bases: object

Utility class used to build custom widgets. Widgets can be made with Python or XML. Use the LayoutManager.register_widget() decorator to register.

build(**kwargs) → Widget: Build the widget. When overriding, use the self.manager, self.element, self.children if applicable.

render_from_xml(xml_path: ~pathlib.Path, resource_handler=<modern_urwid.resource_handler.ResourceHandler object>, css_path: ~pathlib.Path | None = None) → XMLParser: Render a widget from XML. Note: XMLParser.styles will need to be registered in urwid palettes.

Constants

This module contains all of the constants used in modern_urwid.

Module variables:

XML_NS - XML namespace for modern-urwid
RESOURCE_CHAR - The character used to reference resources from ResourceHandler
DEFAULT_STYLE - The default style for widgets

Exceptions

exception modern_urwid.exceptions.InvalidTemplate: Bases: Exception

exception modern_urwid.exceptions.UnknownResource: Bases: Exception