gdamms-pytui 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- gdamms_pytui-0.2.0.dist-info/METADATA +260 -0
- gdamms_pytui-0.2.0.dist-info/RECORD +18 -0
- gdamms_pytui-0.2.0.dist-info/WHEEL +4 -0
- gdamms_pytui-0.2.0.dist-info/licenses/LICENSE +21 -0
- pytui/__init__.py +47 -0
- pytui/app.py +440 -0
- pytui/canvas.py +185 -0
- pytui/events.py +84 -0
- pytui/geometry.py +84 -0
- pytui/input.py +191 -0
- pytui/layout.py +390 -0
- pytui/py.typed +0 -0
- pytui/render.py +91 -0
- pytui/style.py +349 -0
- pytui/terminal.py +135 -0
- pytui/text.py +129 -0
- pytui/widget.py +289 -0
- pytui/widgets.py +674 -0
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: gdamms-pytui
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Build terminal user interfaces in Python with a flexbox-style layout engine.
|
|
5
|
+
Author: gdamms
|
|
6
|
+
Author-email: gdamms <damguillotin@gmail.com>
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Environment :: Console :: Curses
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Operating System :: POSIX
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Topic :: Software Development :: User Interfaces
|
|
15
|
+
Classifier: Typing :: Typed
|
|
16
|
+
Requires-Python: >=3.11
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
|
|
19
|
+
# pytui
|
|
20
|
+
|
|
21
|
+

|
|
22
|
+
|
|
23
|
+
Build terminal user interfaces in Python with ideas borrowed from HTML/CSS:
|
|
24
|
+
a tree of widgets, typed styles, and a flexbox layout engine.
|
|
25
|
+
|
|
26
|
+
- **Flexbox layout**: `direction`, `flex_grow`/`flex_shrink`, `gap`, `justify_content`,
|
|
27
|
+
`align_items`, percentages, min/max sizes, margins, padding, borders, absolute positioning,
|
|
28
|
+
scrollable containers.
|
|
29
|
+
- **Styles as objects**: `Style(...)` merged with `|`, inherited text attributes, and
|
|
30
|
+
`hover` / `focus` / `focus_within` / `disabled` state variants.
|
|
31
|
+
- **Widgets**: `Box`, `Row`, `Column`, `Text`, `Button`, `Checkbox`, `Input`, `TextArea`,
|
|
32
|
+
`ListView`, `ProgressBar`, and an easy way to write your own.
|
|
33
|
+
- **Input**: keyboard with modifiers, mouse (click, drag, hover, wheel), bracketed paste,
|
|
34
|
+
focus navigation with Tab.
|
|
35
|
+
- **Efficient rendering**: an in-memory cell buffer diffed against the previous frame, so only
|
|
36
|
+
changed cells are written. Wide (CJK/emoji) characters are handled.
|
|
37
|
+
- **Testable**: render to text and simulate input without a terminal.
|
|
38
|
+
- **Zero dependencies**, pure Python >= 3.11 (Linux/macOS). (Might work with lower Python versions, but not tested.)
|
|
39
|
+
|
|
40
|
+
## Install
|
|
41
|
+
|
|
42
|
+
```sh
|
|
43
|
+
git clone https://github.com/gdamms/pytui.git
|
|
44
|
+
uv add pytui
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
One day, I'll publish it to PyPI...
|
|
48
|
+
|
|
49
|
+
## Quick start
|
|
50
|
+
|
|
51
|
+
```python
|
|
52
|
+
from pytui import App, Box, Button, Row, Text
|
|
53
|
+
|
|
54
|
+
count = Text("Clicked 0 times")
|
|
55
|
+
clicks = 0
|
|
56
|
+
|
|
57
|
+
def on_click():
|
|
58
|
+
global clicks
|
|
59
|
+
clicks += 1
|
|
60
|
+
count.text = f"Clicked {clicks} times"
|
|
61
|
+
|
|
62
|
+
app = App(
|
|
63
|
+
Box(
|
|
64
|
+
Text("Hello from pytui!", bold=True, fg="cyan"),
|
|
65
|
+
count,
|
|
66
|
+
Row(Button("Click me", on_press=on_click), Button("Quit", on_press=lambda: app.exit()), gap=2),
|
|
67
|
+
border="rounded", title="hello", padding=(1, 2), gap=1,
|
|
68
|
+
align_items="center", justify_content="center",
|
|
69
|
+
)
|
|
70
|
+
)
|
|
71
|
+
app.run()
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The screen is redrawn automatically after every event, timer or thread callback, so
|
|
75
|
+
changing widget attributes (`count.text = ...`) is all it takes to update the UI.
|
|
76
|
+
|
|
77
|
+
Try the examples:
|
|
78
|
+
|
|
79
|
+
```sh
|
|
80
|
+
uv run examples/hello.py # from the quick start
|
|
81
|
+
uv run examples/notes.py # list + editor, key bindings, focus styles
|
|
82
|
+
uv run examples/dashboard.py # timers, background thread, scrolling log
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Layout
|
|
86
|
+
|
|
87
|
+
Every widget is a flex container, like `display: flex` in CSS. Children are laid out along the
|
|
88
|
+
main axis (`direction`, default `"column"`) and aligned on the cross axis.
|
|
89
|
+
|
|
90
|
+
| Property | Values | Default |
|
|
91
|
+
| --- | --- | --- |
|
|
92
|
+
| `width`, `height` | `int` cells, `"50%"` of the parent, `"auto"` | `"auto"` (fit content) |
|
|
93
|
+
| `min_width`, `max_width`, `min_height`, `max_height` | same | none |
|
|
94
|
+
| `box_sizing` | `"border-box"`, `"content-box"` | `"border-box"` |
|
|
95
|
+
| `margin`, `padding` | `1`, `(vertical, horizontal)`, `(top, right, bottom, left)` | `0` |
|
|
96
|
+
| `border` | `"none"`, `"single"`, `"double"`, `"rounded"`, `"heavy"`, `"ascii"`, `"blank"` or 8 custom chars | `"none"` |
|
|
97
|
+
| `direction` | `"row"`, `"column"` | `"column"` |
|
|
98
|
+
| `gap` | `int` | `0` |
|
|
99
|
+
| `justify_content` | `"start"`, `"center"`, `"end"`, `"space-between"`, `"space-around"`, `"space-evenly"` | `"start"` |
|
|
100
|
+
| `align_items` | `"start"`, `"center"`, `"end"`, `"stretch"` | `"stretch"` |
|
|
101
|
+
| `align_self` | `"auto"` or an `align_items` value | `"auto"` |
|
|
102
|
+
| `flex_grow`, `flex_shrink` | `float` | `0`, `1` |
|
|
103
|
+
| `position` | `"relative"`, `"absolute"` (with `top`/`right`/`bottom`/`left`) | `"relative"` |
|
|
104
|
+
| `display` | `"flex"`, `"none"` (removed from layout) | `"flex"` |
|
|
105
|
+
| `visibility` | `"visible"`, `"hidden"` (keeps its space) | `"visible"` |
|
|
106
|
+
| `overflow` | `"hidden"`, `"visible"`, `"scroll"` | `"hidden"` |
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
Row(
|
|
110
|
+
Box(sidebar, width=30, flex_shrink=0, border="rounded", title="Files"),
|
|
111
|
+
Box(editor, flex_grow=1, border="rounded"), # takes the remaining space
|
|
112
|
+
Box(help_panel, width="25%", display="none", id="help"), # toggled later
|
|
113
|
+
)
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
`overflow="scroll"` makes a container scrollable. Its children keep their natural size, and it
|
|
117
|
+
scrolls with the mouse wheel, with the keyboard when it is focusable (`focusable=True`), and
|
|
118
|
+
automatically to reveal the focused widget. A scrollbar is drawn on the right border, or in a
|
|
119
|
+
reserved column if there is no border.
|
|
120
|
+
|
|
121
|
+
## Styling
|
|
122
|
+
|
|
123
|
+
Style fields can be passed as keyword arguments or as a `Style` object. Styles combine with
|
|
124
|
+
`|`, and the right-hand side wins:
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
from pytui import Style
|
|
128
|
+
|
|
129
|
+
card = Style(border="rounded", padding=(0, 1), border_fg="bright_black")
|
|
130
|
+
active = card | Style(border_fg="cyan", bold=True)
|
|
131
|
+
|
|
132
|
+
Box(Text("hello"), style=card, margin=1) # keywords are merged on top of `style`
|
|
133
|
+
widget.set_style(fg="red") # change it later
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
- **Text attributes** `fg`, `bg`, `bold`, `dim`, `italic`, `underline`, `strike`, `reverse`,
|
|
137
|
+
`text_align`, `text_wrap` are **inherited** by children.
|
|
138
|
+
- **Colors**: names (`"red"`, `"bright_blue"`, `"gray"`, `"default"`), `"#rrggbb"`, or a
|
|
139
|
+
256-color index.
|
|
140
|
+
- **States** are nested styles applied while the state is active:
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
Button("Save", style=Style(
|
|
144
|
+
bg="green",
|
|
145
|
+
hover=Style(bg="bright_green"),
|
|
146
|
+
focus=Style(bold=True, underline=True),
|
|
147
|
+
disabled=Style(dim=True),
|
|
148
|
+
))
|
|
149
|
+
Box(..., focus_within=Style(border_fg="cyan")) # when a descendant has focus
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Each widget class has a `DEFAULT_STYLE` that instance styles override. To theme a widget
|
|
153
|
+
everywhere, subclass it:
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
class DangerButton(Button):
|
|
157
|
+
DEFAULT_STYLE = Button.DEFAULT_STYLE | Style(bg="red", focus=Style(bg="bright_red"))
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
## Widgets
|
|
161
|
+
|
|
162
|
+
| Widget | Purpose | Callbacks |
|
|
163
|
+
| --- | --- | --- |
|
|
164
|
+
| `Box(*children, title=None)` | Generic container (`Row` / `Column` preset the direction) | |
|
|
165
|
+
| `Text(text)` | Text, word-wrapped unless `text_wrap=False` | |
|
|
166
|
+
| `Button(label)` | Pressed with click, Enter or Space | `on_press()` |
|
|
167
|
+
| `Checkbox(label, checked)` | Toggle | `on_change(checked)` |
|
|
168
|
+
| `Input(value, placeholder=, password=)` | Single-line text field | `on_change(value)`, `on_submit(value)` |
|
|
169
|
+
| `TextArea(value)` | Multi-line editor | `on_change(value)` |
|
|
170
|
+
| `ListView(items)` | Scrollable list with a highlighted row | `on_select(i, item)`, `on_highlight(i, item)` |
|
|
171
|
+
| `ProgressBar(value)` | `value` between 0 and 1 | |
|
|
172
|
+
|
|
173
|
+
Common widget API: `id=`, `disabled=`, `focusable=`, `mount(*children)`, `remove()`,
|
|
174
|
+
`clear()`, `find(id)`, `get(id, Type)`, `walk()`, `focus()`, `hidden = True`, `bind(key, fn)`,
|
|
175
|
+
`scroll_to()`, and `region` / `content_region` (screen rectangles after layout).
|
|
176
|
+
|
|
177
|
+
## Events, focus and key bindings
|
|
178
|
+
|
|
179
|
+
- Keys go to the focused widget, then bubble up through its ancestors, then to app bindings.
|
|
180
|
+
Tab / Shift+Tab move focus if nothing handled the key.
|
|
181
|
+
- Mouse events go to the widget under the pointer and bubble up. A press focuses the nearest
|
|
182
|
+
focusable widget, and press+release on the same widget is a click.
|
|
183
|
+
- Key names look like `"a"`, `"A"`, `"space"`, `"enter"`, `"escape"`, `"tab"`, `"shift+tab"`,
|
|
184
|
+
`"up"`, `"pageup"`, `"f5"`, `"ctrl+s"`, `"alt+x"`, `"ctrl+shift+left"`.
|
|
185
|
+
|
|
186
|
+
```python
|
|
187
|
+
app.bind("ctrl+q", app.exit) # global
|
|
188
|
+
editor.bind("ctrl+s", save) # only while focus is inside `editor`
|
|
189
|
+
app.bind("f1 ctrl+h", lambda: help.set_style(display="flex"))
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
`ctrl+c` exits by default (`app.unbind("ctrl+c")` to disable). `app.run()` returns the value
|
|
193
|
+
passed to `app.exit(value)`.
|
|
194
|
+
|
|
195
|
+
## Timers and threads
|
|
196
|
+
|
|
197
|
+
```python
|
|
198
|
+
timer = app.set_interval(1.0, update_clock) # timer.cancel() to stop
|
|
199
|
+
app.call_later(0.5, lambda: status.set_style(display="none"))
|
|
200
|
+
|
|
201
|
+
def worker(): # in another thread
|
|
202
|
+
result = slow_computation()
|
|
203
|
+
app.call_from_thread(show_result, result) # thread-safe, redraws afterwards
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
## Custom widgets
|
|
207
|
+
|
|
208
|
+
Subclass `Widget`, describe the content size, and draw into the canvas:
|
|
209
|
+
|
|
210
|
+
```python
|
|
211
|
+
from pytui import Style, Widget
|
|
212
|
+
|
|
213
|
+
class Counter(Widget):
|
|
214
|
+
FOCUSABLE = True
|
|
215
|
+
DEFAULT_STYLE = Style(padding=(0, 1), focus=Style(reverse=True))
|
|
216
|
+
|
|
217
|
+
def __init__(self, **kwargs):
|
|
218
|
+
super().__init__(**kwargs)
|
|
219
|
+
self.value = 0
|
|
220
|
+
|
|
221
|
+
def content_width(self) -> int:
|
|
222
|
+
return len(f"count: {self.value}")
|
|
223
|
+
|
|
224
|
+
def content_height(self, width: int) -> int:
|
|
225
|
+
return 1
|
|
226
|
+
|
|
227
|
+
def render(self, canvas):
|
|
228
|
+
area = self.content_region
|
|
229
|
+
canvas.text(area.x, area.y, f"count: {self.value}", self.text_style)
|
|
230
|
+
|
|
231
|
+
def on_key(self, event) -> bool:
|
|
232
|
+
if event.key in ("up", "+"):
|
|
233
|
+
self.value += 1
|
|
234
|
+
return True # handled: stop propagation
|
|
235
|
+
if event.key in ("down", "-"):
|
|
236
|
+
self.value -= 1
|
|
237
|
+
return True
|
|
238
|
+
return False
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
Background, border, children and clipping are handled for you. Other hooks are `on_mouse`,
|
|
242
|
+
`on_click`, `on_paste`, `on_focus` and `on_blur`.
|
|
243
|
+
|
|
244
|
+
## Testing your UI
|
|
245
|
+
|
|
246
|
+
No terminal needed: render to text and simulate input.
|
|
247
|
+
|
|
248
|
+
```python
|
|
249
|
+
def test_login_form():
|
|
250
|
+
name = Input(id="name")
|
|
251
|
+
submitted = []
|
|
252
|
+
app = App(Box(name, Button("Login", on_press=lambda: submitted.append(name.value))))
|
|
253
|
+
|
|
254
|
+
app.render(40, 5)
|
|
255
|
+
app.feed("alice") # raw terminal input: text, escape sequences, mouse reports
|
|
256
|
+
app.press("tab", "enter") # key names
|
|
257
|
+
assert submitted == ["alice"]
|
|
258
|
+
assert "alice" in app.snapshot()
|
|
259
|
+
app.click(0, 1) # mouse click at screen coordinates
|
|
260
|
+
```
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
pytui/__init__.py,sha256=P4-lQPGD7zO74lOwR_qBIxoiDHJ-5NFF2jU7zErDLWI,825
|
|
2
|
+
pytui/app.py,sha256=eBgGc3k9wSXSX-GICzaEfpfgllj2970mCMcbedcsfoE,16745
|
|
3
|
+
pytui/canvas.py,sha256=mc-jXQhr9eMJvfmhuadghntzEFFAlSeVyb69aXsZje4,6656
|
|
4
|
+
pytui/events.py,sha256=cLYv5YlSDYwY8CuEjfa_hPp_wkgWPLoYg8jjXwYLaCE,2281
|
|
5
|
+
pytui/geometry.py,sha256=P-OMY1slDiCPGm-tm25VDzlqHbdB3iABApuEekABlis,2416
|
|
6
|
+
pytui/input.py,sha256=sql7fjIbQhmn4oOxfJxxyRAWXE_RAy9leAT3cqt6y6M,6352
|
|
7
|
+
pytui/layout.py,sha256=e3W5vJkyEhcy4FUaEBQuIDD_zERhMr_sqXCneD_jivo,16284
|
|
8
|
+
pytui/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
9
|
+
pytui/render.py,sha256=5emRKp_m-ttfkYJPmUeHy1R8JJnxpk1ysnAM9CqmF_0,3269
|
|
10
|
+
pytui/style.py,sha256=ITqHTDuCwrqII57oOS8aPhHSSJQvenIIDnnZ9YeeFwM,12085
|
|
11
|
+
pytui/terminal.py,sha256=VMODa8yY2sIKvgjIYnQmos4d4_OiY9YqHl6sJ085ups,4812
|
|
12
|
+
pytui/text.py,sha256=JVQ-TDF5_TGRFLIJdTowF4SNUzLLNFZ5jwnWR24kxqU,4051
|
|
13
|
+
pytui/widget.py,sha256=xJHpNKYfV13x7u9BuHQpovhydnFwng-WPLpFw09ccNQ,9996
|
|
14
|
+
pytui/widgets.py,sha256=kCobPrWkgOuRKWBhWC20sLPcci99BhmOkogv7btW9UM,23238
|
|
15
|
+
gdamms_pytui-0.2.0.dist-info/licenses/LICENSE,sha256=fc4COfU5qyNCG0LFs9kgvwEU54Zl6HgsFHzgDrZb2nA,1073
|
|
16
|
+
gdamms_pytui-0.2.0.dist-info/WHEEL,sha256=3NO1oYsF7mANFUWVdyEQLM-zmecczWWEmmF5rEbXrWk,80
|
|
17
|
+
gdamms_pytui-0.2.0.dist-info/METADATA,sha256=gkgP4f2GiV6P44vVjWcVm2_eMe-Z2OXhdhVpm-YDSrs,9860
|
|
18
|
+
gdamms_pytui-0.2.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Damien Guillotin
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
pytui/__init__.py
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
"""pytui: build terminal user interfaces with a flexbox-style layout engine."""
|
|
2
|
+
|
|
3
|
+
from .app import App, Timer
|
|
4
|
+
from .canvas import Canvas, CellStyle
|
|
5
|
+
from .events import Event, KeyEvent, MouseEvent, PasteEvent, ResizeEvent
|
|
6
|
+
from .geometry import Edges, Rect
|
|
7
|
+
from .style import BORDERS, Style
|
|
8
|
+
from .widget import Widget
|
|
9
|
+
from .widgets import (
|
|
10
|
+
Box,
|
|
11
|
+
Button,
|
|
12
|
+
Checkbox,
|
|
13
|
+
Column,
|
|
14
|
+
Input,
|
|
15
|
+
ListView,
|
|
16
|
+
ProgressBar,
|
|
17
|
+
Row,
|
|
18
|
+
Text,
|
|
19
|
+
TextArea,
|
|
20
|
+
)
|
|
21
|
+
|
|
22
|
+
__all__ = [
|
|
23
|
+
"BORDERS",
|
|
24
|
+
"App",
|
|
25
|
+
"Box",
|
|
26
|
+
"Button",
|
|
27
|
+
"Canvas",
|
|
28
|
+
"CellStyle",
|
|
29
|
+
"Checkbox",
|
|
30
|
+
"Column",
|
|
31
|
+
"Edges",
|
|
32
|
+
"Event",
|
|
33
|
+
"Input",
|
|
34
|
+
"KeyEvent",
|
|
35
|
+
"ListView",
|
|
36
|
+
"MouseEvent",
|
|
37
|
+
"PasteEvent",
|
|
38
|
+
"ProgressBar",
|
|
39
|
+
"Rect",
|
|
40
|
+
"ResizeEvent",
|
|
41
|
+
"Row",
|
|
42
|
+
"Style",
|
|
43
|
+
"Text",
|
|
44
|
+
"TextArea",
|
|
45
|
+
"Timer",
|
|
46
|
+
"Widget",
|
|
47
|
+
]
|