pytermgui

Welcome to the API reference for PyTermGUI, a Python TUI framework with mouse support, modular widget system, customizable and rapid terminal markup language and more!

  1"""
  2Welcome to the API reference for **PyTermGUI**, a Python TUI framework with mouse
  3support, modular widget system, customizable and rapid terminal markup language and
  4more!
  5"""
  6
  7# https://github.com/python/mypy/issues/4930
  8# mypy: ignore-errors
  9
 10from __future__ import annotations
 11
 12import sys
 13from typing import Any, Optional
 14
 15from .animations import *
 16from .ansi_interface import *
 17from .colors import *
 18from .context_managers import alt_buffer, cursor_at, mouse_handler
 19from .enums import *
 20from .exceptions import *
 21from .exporters import *
 22from .fancy_repr import *
 23from .file_loaders import *
 24from .helpers import *
 25from .highlighters import *
 26from .input import getch, keys
 27from .inspector import *
 28from .markup import *
 29from .palettes import *
 30from .prettifiers import *
 31from .regex import *
 32from .serialization import *
 33from .term import *
 34from .widgets import *
 35from .window_manager import *
 36
 37# Silence warning if running as standalone module
 38if "-m" in sys.argv:  # pragma: no cover
 39    import warnings
 40
 41    warnings.filterwarnings("ignore")
 42
 43__version__ = "7.4.0"
 44
 45
 46def auto(data: Any, **widget_args: Any) -> Optional[Widget | list[Splitter]]:
 47    """Creates a widget from specific data structures.
 48
 49    This conversion includes various widget classes, as well as some shorthands for
 50    more complex objects.  This method is called implicitly whenever a non-widget is
 51    attempted to be added to a Widget.
 52
 53    You can read up on the syntacies for each builtin widget within the widget
 54    [documentation](/widgets/builtins).
 55
 56    Args:
 57        data: The structure to convert. See below for formats.
 58        **widget_args: Arguments passed straight to the widget constructor.
 59
 60    Returns:
 61        The widget or list of widgets created, or None if the passed structure could
 62        not be converted.
 63
 64    Example:
 65
 66    ```python3
 67    from pytermgui import Container
 68    form = (
 69        Container(id="form")
 70        + "[157 bold]This is a title"
 71        + ""
 72        + {"[72 italic]Label1": "[210]Button1"}
 73        + {"[72 italic]Label2": "[210]Button2"}
 74        + {"[72 italic]Label3": "[210]Button3"}
 75        + ""
 76        + ["Submit", lambda _, button, your_submit_handler(button.parent)]
 77    )
 78    ```
 79    """
 80    # In my opinion, returning immediately after construction is much more readable.
 81    # pylint: disable=too-many-return-statements
 82
 83    # Nothing to do.
 84    if isinstance(data, Widget):
 85        # Set all **widget_args
 86        for key, value in widget_args.items():
 87            setattr(data, key, value)
 88
 89        return data
 90
 91    # Label
 92    if isinstance(data, str):
 93        return Label(data, **widget_args)
 94
 95    # Splitter
 96    if isinstance(data, tuple):
 97        return Splitter(*data, **widget_args)
 98
 99    # buttons
100    if isinstance(data, list):
101        label = data[0]
102        onclick = None
103        if len(data) > 1:
104            onclick = data[1]
105
106        # Checkbox
107        if isinstance(label, bool):
108            return Checkbox(onclick, checked=label, **widget_args)
109
110        # Toggle
111        if isinstance(label, tuple):
112            assert len(label) == 2
113            return Toggle(label, onclick, **widget_args)
114
115        return Button(label, onclick, **widget_args)
116
117    # prompt splitter
118    if isinstance(data, dict):
119        rows: list[Splitter] = []
120
121        for key, value in data.items():
122            left = auto(key, parent_align=HorizontalAlignment.LEFT)
123            right = auto(value, parent_align=HorizontalAlignment.RIGHT)
124
125            rows.append(Splitter(left, right, **widget_args))
126
127        if len(rows) == 1:
128            return rows[0]
129
130        return rows
131
132    return None
133
134
135# Alternative binding for the `auto` method
136Widget.from_data = staticmethod(auto)
def auto( data: Any, **widget_args: Any) -> Union[pytermgui.widgets.base.Widget, list[pytermgui.widgets.containers.Splitter], NoneType]:
 47def auto(data: Any, **widget_args: Any) -> Optional[Widget | list[Splitter]]:
 48    """Creates a widget from specific data structures.
 49
 50    This conversion includes various widget classes, as well as some shorthands for
 51    more complex objects.  This method is called implicitly whenever a non-widget is
 52    attempted to be added to a Widget.
 53
 54    You can read up on the syntacies for each builtin widget within the widget
 55    [documentation](/widgets/builtins).
 56
 57    Args:
 58        data: The structure to convert. See below for formats.
 59        **widget_args: Arguments passed straight to the widget constructor.
 60
 61    Returns:
 62        The widget or list of widgets created, or None if the passed structure could
 63        not be converted.
 64
 65    Example:
 66
 67    ```python3
 68    from pytermgui import Container
 69    form = (
 70        Container(id="form")
 71        + "[157 bold]This is a title"
 72        + ""
 73        + {"[72 italic]Label1": "[210]Button1"}
 74        + {"[72 italic]Label2": "[210]Button2"}
 75        + {"[72 italic]Label3": "[210]Button3"}
 76        + ""
 77        + ["Submit", lambda _, button, your_submit_handler(button.parent)]
 78    )
 79    ```
 80    """
 81    # In my opinion, returning immediately after construction is much more readable.
 82    # pylint: disable=too-many-return-statements
 83
 84    # Nothing to do.
 85    if isinstance(data, Widget):
 86        # Set all **widget_args
 87        for key, value in widget_args.items():
 88            setattr(data, key, value)
 89
 90        return data
 91
 92    # Label
 93    if isinstance(data, str):
 94        return Label(data, **widget_args)
 95
 96    # Splitter
 97    if isinstance(data, tuple):
 98        return Splitter(*data, **widget_args)
 99
100    # buttons
101    if isinstance(data, list):
102        label = data[0]
103        onclick = None
104        if len(data) > 1:
105            onclick = data[1]
106
107        # Checkbox
108        if isinstance(label, bool):
109            return Checkbox(onclick, checked=label, **widget_args)
110
111        # Toggle
112        if isinstance(label, tuple):
113            assert len(label) == 2
114            return Toggle(label, onclick, **widget_args)
115
116        return Button(label, onclick, **widget_args)
117
118    # prompt splitter
119    if isinstance(data, dict):
120        rows: list[Splitter] = []
121
122        for key, value in data.items():
123            left = auto(key, parent_align=HorizontalAlignment.LEFT)
124            right = auto(value, parent_align=HorizontalAlignment.RIGHT)
125
126            rows.append(Splitter(left, right, **widget_args))
127
128        if len(rows) == 1:
129            return rows[0]
130
131        return rows
132
133    return None

Creates a widget from specific data structures.

This conversion includes various widget classes, as well as some shorthands for more complex objects. This method is called implicitly whenever a non-widget is attempted to be added to a Widget.

You can read up on the syntacies for each builtin widget within the widget documentation.

Arguments:
  • data: The structure to convert. See below for formats.
  • **widget_args: Arguments passed straight to the widget constructor.
Returns:

The widget or list of widgets created, or None if the passed structure could not be converted.

Example:

from pytermgui import Container
form = (
    Container(id="form")
    + "[157 bold]This is a title"
    + ""
    + {"[72 italic]Label1": "[210]Button1"}
    + {"[72 italic]Label2": "[210]Button2"}
    + {"[72 italic]Label3": "[210]Button3"}
    + ""
    + ["Submit", lambda _, button, your_submit_handler(button.parent)]
)