Theme

Controlling visual aspects of Yuio with themes.

Theme base class

The overall look and feel of a Yuio application is declared in a Theme object:

class yuio.theme.Theme

Base class for Yuio themes.

progress_bar_width: int = 15

Width of a progress bar for yuio.io.Task.

progress_bar_start_symbol: str = ''

A symbol rendered on a left side of a progressbar.

Set to '[' to enclose progressbar in square brackets, for example.

progress_bar_end_symbol: str = ''

A symbol rendered on a right side of a progressbar.

Set to ']' to enclose progressbar in square brackets, for example.

progress_bar_done_symbol: str = '■'

Symbol rendered in the filled portion of a progressbar.

progress_bar_pending_symbol: str = '□'

Symbol rendered in the unfilled portion of a progressbar.

spinner_pattern: Sequence[str] = '⣤⣤⣤⠶⠛⠛⠛⠶'

Spinner pattern for running tasks that don’t have a progressbar.

Every tick, a symbol in front of a task’s heading updates, showing elements of this sequence.

spinner_update_rate_ms: int = 200

How often the spinner_pattern changes.

spinner_static_symbol = '⣿'

Symbol for finished and failed tasks.

It meant to resemble a static spinner.

msg_decorations: Mapping[str, str] = {'heading/section': '', 'heading/1': '⣿ ', 'heading/2': '', 'heading/3': '', 'heading/4': '', 'heading/5': '', 'heading/6': '', 'question': '> ', 'task': '> ', 'thematic_break': '╌╌╌╌╌', 'list': '•   ', 'quote': '>   ', 'code': '        '}

Decorative symbols for certain text elements, such as headings, list items, etc.

This mapping becomes immutable once a theme class is created. The only possible way to modify it is by using set_msg_decoration() or _set_msg_decoration_if_not_overridden().

set_msg_decoration(name: str, msg_decoration: str, /)

Set message decoration by name.

_set_msg_decoration_if_not_overridden(name: str, msg_decoration: str, /)

Set message decoration by name, but only if it wasn’t overridden in a subclass.

This method should be called from __init__ implementations to dynamically set message decorations. It will only set the decoration if it was not overridden by any child class.

colors: Mapping[str, str | Color | List[Color | str]] = {'code': 'magenta', 'note': 'green', 'bold': Color(fore=None, back=None, bold=True, dim=None), 'b': 'bold', 'dim': Color(fore=None, back=None, bold=None, dim=True), 'd': 'dim', 'normal': Color(fore=<ColorValue 9>, back=None, bold=None, dim=None), 'normal_dim': Color(fore=<ColorValue 2>, back=None, bold=None, dim=None), 'red': Color(fore=<ColorValue 1>, back=None, bold=None, dim=None), 'green': Color(fore=<ColorValue 2>, back=None, bold=None, dim=None), 'yellow': Color(fore=<ColorValue 3>, back=None, bold=None, dim=None), 'blue': Color(fore=<ColorValue 4>, back=None, bold=None, dim=None), 'magenta': Color(fore=<ColorValue 5>, back=None, bold=None, dim=None), 'cyan': Color(fore=<ColorValue 6>, back=None, bold=None, dim=None)}

Mapping of color paths to actual colors.

Themes use color paths to describe styles and colors for different parts of an application. Color paths are similar to file paths, they use snake case identifiers separated by slashes, and consist of two parts separated by a colon.

The first part represents an object, i.e. what are we coloring.

The second part represents a context, i.e. what is the state or location of an object that we’re coloring.

For example, a color for the filled part of the task’s progress bar has path 'task/progressbar/done', a color for a text of an error log record has path 'log/message:error', and a color for a string escape sequence in a highlighted python code has path 'hl/str/esc:python'.

A color at a certain path is propagated to all sub-paths. For example, if 'task/progressbar' is bold, and 'task/progressbar/done' is green, the final color will be bold green.

Each color path can be associated with either an instance of Color, another path, or a list of colors and paths.

If path is mapped to a Color, then the path is associated with that particular color.

If path is mapped to another path, then the path is associated with the color value for that other path (please don’t create recursions here).

If path is mapped to a list of colors and paths, then those colors and paths are combined.

For example:

colors = {
    'heading_color': Color.BOLD,
    'error_color': Color.RED,
    'tb/heading': ['heading_color', 'error_color'],
}

Here, color of traceback’s heading 'tb/heading' will be bold and red.

The base theme class provides colors for basic tags, such as bold, red, code, note, etc. DefaultTheme expands on it, providing main colors that control the overall look of the theme, and then colors for all interface elements.

When deriving from a theme, you can override this mapping. When looking up colors via get_color(), base classes will be tried for color, in order of method resolution.

This mapping becomes immutable once a theme class is created. The only possible way to modify it is by using set_color() or _set_color_if_not_overridden().

set_color(path: str, color: str | Color | List[Color | str], /)

Set color by path.

_set_color_if_not_overridden(path: str, color: str | Color | List[Color | str], /)

Set color by path, but only if the color was not overridden in a subclass.

This method should be called from __init__ implementations to dynamically set colors. It will only set the color if it was not overridden by any child class.

get_color(path: str, /) → Color

Lookup a color by path.

to_color(color_or_path: Color | str | None) → Color

Convert color or color path to color.

Default theme

Use the following loader to create an instance of the default theme:

yuio.theme.load(term: Term, /) → Theme

Loads a default theme.

class yuio.theme.DefaultTheme(term: Term)

Default Yuio theme. Adapts for terminal background color, if one can be detected.

This theme defines main colors, which you can override by subclassing.

• 'heading_color': for headings,

• 'primary_color': for main text,

• 'accent_color': for visually highlighted elements,

• 'secondary_color': for visually dimmed elements,

• 'error_color': for everything that indicates an error,

• 'warning_color': for everything that indicates a warning,

• 'success_color': for everything that indicates a success,

• 'low_priority_color_a': for auxiliary elements such as help widget,

• 'low_priority_color_b': for auxiliary elements such as help widget, even lower priority.