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.
@@ -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
+ ![Screenshot](assets/screenshot.png)
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,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: uv 0.13.6
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -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
+ ]