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)]
)