gdamms-pytui 0.2.0__tar.gz

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,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.
@@ -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,242 @@
1
+ # pytui
2
+
3
+ ![Screenshot](assets/screenshot.png)
4
+
5
+ Build terminal user interfaces in Python with ideas borrowed from HTML/CSS:
6
+ a tree of widgets, typed styles, and a flexbox layout engine.
7
+
8
+ - **Flexbox layout**: `direction`, `flex_grow`/`flex_shrink`, `gap`, `justify_content`,
9
+ `align_items`, percentages, min/max sizes, margins, padding, borders, absolute positioning,
10
+ scrollable containers.
11
+ - **Styles as objects**: `Style(...)` merged with `|`, inherited text attributes, and
12
+ `hover` / `focus` / `focus_within` / `disabled` state variants.
13
+ - **Widgets**: `Box`, `Row`, `Column`, `Text`, `Button`, `Checkbox`, `Input`, `TextArea`,
14
+ `ListView`, `ProgressBar`, and an easy way to write your own.
15
+ - **Input**: keyboard with modifiers, mouse (click, drag, hover, wheel), bracketed paste,
16
+ focus navigation with Tab.
17
+ - **Efficient rendering**: an in-memory cell buffer diffed against the previous frame, so only
18
+ changed cells are written. Wide (CJK/emoji) characters are handled.
19
+ - **Testable**: render to text and simulate input without a terminal.
20
+ - **Zero dependencies**, pure Python >= 3.11 (Linux/macOS). (Might work with lower Python versions, but not tested.)
21
+
22
+ ## Install
23
+
24
+ ```sh
25
+ git clone https://github.com/gdamms/pytui.git
26
+ uv add pytui
27
+ ```
28
+
29
+ One day, I'll publish it to PyPI...
30
+
31
+ ## Quick start
32
+
33
+ ```python
34
+ from pytui import App, Box, Button, Row, Text
35
+
36
+ count = Text("Clicked 0 times")
37
+ clicks = 0
38
+
39
+ def on_click():
40
+ global clicks
41
+ clicks += 1
42
+ count.text = f"Clicked {clicks} times"
43
+
44
+ app = App(
45
+ Box(
46
+ Text("Hello from pytui!", bold=True, fg="cyan"),
47
+ count,
48
+ Row(Button("Click me", on_press=on_click), Button("Quit", on_press=lambda: app.exit()), gap=2),
49
+ border="rounded", title="hello", padding=(1, 2), gap=1,
50
+ align_items="center", justify_content="center",
51
+ )
52
+ )
53
+ app.run()
54
+ ```
55
+
56
+ The screen is redrawn automatically after every event, timer or thread callback, so
57
+ changing widget attributes (`count.text = ...`) is all it takes to update the UI.
58
+
59
+ Try the examples:
60
+
61
+ ```sh
62
+ uv run examples/hello.py # from the quick start
63
+ uv run examples/notes.py # list + editor, key bindings, focus styles
64
+ uv run examples/dashboard.py # timers, background thread, scrolling log
65
+ ```
66
+
67
+ ## Layout
68
+
69
+ Every widget is a flex container, like `display: flex` in CSS. Children are laid out along the
70
+ main axis (`direction`, default `"column"`) and aligned on the cross axis.
71
+
72
+ | Property | Values | Default |
73
+ | --- | --- | --- |
74
+ | `width`, `height` | `int` cells, `"50%"` of the parent, `"auto"` | `"auto"` (fit content) |
75
+ | `min_width`, `max_width`, `min_height`, `max_height` | same | none |
76
+ | `box_sizing` | `"border-box"`, `"content-box"` | `"border-box"` |
77
+ | `margin`, `padding` | `1`, `(vertical, horizontal)`, `(top, right, bottom, left)` | `0` |
78
+ | `border` | `"none"`, `"single"`, `"double"`, `"rounded"`, `"heavy"`, `"ascii"`, `"blank"` or 8 custom chars | `"none"` |
79
+ | `direction` | `"row"`, `"column"` | `"column"` |
80
+ | `gap` | `int` | `0` |
81
+ | `justify_content` | `"start"`, `"center"`, `"end"`, `"space-between"`, `"space-around"`, `"space-evenly"` | `"start"` |
82
+ | `align_items` | `"start"`, `"center"`, `"end"`, `"stretch"` | `"stretch"` |
83
+ | `align_self` | `"auto"` or an `align_items` value | `"auto"` |
84
+ | `flex_grow`, `flex_shrink` | `float` | `0`, `1` |
85
+ | `position` | `"relative"`, `"absolute"` (with `top`/`right`/`bottom`/`left`) | `"relative"` |
86
+ | `display` | `"flex"`, `"none"` (removed from layout) | `"flex"` |
87
+ | `visibility` | `"visible"`, `"hidden"` (keeps its space) | `"visible"` |
88
+ | `overflow` | `"hidden"`, `"visible"`, `"scroll"` | `"hidden"` |
89
+
90
+ ```python
91
+ Row(
92
+ Box(sidebar, width=30, flex_shrink=0, border="rounded", title="Files"),
93
+ Box(editor, flex_grow=1, border="rounded"), # takes the remaining space
94
+ Box(help_panel, width="25%", display="none", id="help"), # toggled later
95
+ )
96
+ ```
97
+
98
+ `overflow="scroll"` makes a container scrollable. Its children keep their natural size, and it
99
+ scrolls with the mouse wheel, with the keyboard when it is focusable (`focusable=True`), and
100
+ automatically to reveal the focused widget. A scrollbar is drawn on the right border, or in a
101
+ reserved column if there is no border.
102
+
103
+ ## Styling
104
+
105
+ Style fields can be passed as keyword arguments or as a `Style` object. Styles combine with
106
+ `|`, and the right-hand side wins:
107
+
108
+ ```python
109
+ from pytui import Style
110
+
111
+ card = Style(border="rounded", padding=(0, 1), border_fg="bright_black")
112
+ active = card | Style(border_fg="cyan", bold=True)
113
+
114
+ Box(Text("hello"), style=card, margin=1) # keywords are merged on top of `style`
115
+ widget.set_style(fg="red") # change it later
116
+ ```
117
+
118
+ - **Text attributes** `fg`, `bg`, `bold`, `dim`, `italic`, `underline`, `strike`, `reverse`,
119
+ `text_align`, `text_wrap` are **inherited** by children.
120
+ - **Colors**: names (`"red"`, `"bright_blue"`, `"gray"`, `"default"`), `"#rrggbb"`, or a
121
+ 256-color index.
122
+ - **States** are nested styles applied while the state is active:
123
+
124
+ ```python
125
+ Button("Save", style=Style(
126
+ bg="green",
127
+ hover=Style(bg="bright_green"),
128
+ focus=Style(bold=True, underline=True),
129
+ disabled=Style(dim=True),
130
+ ))
131
+ Box(..., focus_within=Style(border_fg="cyan")) # when a descendant has focus
132
+ ```
133
+
134
+ Each widget class has a `DEFAULT_STYLE` that instance styles override. To theme a widget
135
+ everywhere, subclass it:
136
+
137
+ ```python
138
+ class DangerButton(Button):
139
+ DEFAULT_STYLE = Button.DEFAULT_STYLE | Style(bg="red", focus=Style(bg="bright_red"))
140
+ ```
141
+
142
+ ## Widgets
143
+
144
+ | Widget | Purpose | Callbacks |
145
+ | --- | --- | --- |
146
+ | `Box(*children, title=None)` | Generic container (`Row` / `Column` preset the direction) | |
147
+ | `Text(text)` | Text, word-wrapped unless `text_wrap=False` | |
148
+ | `Button(label)` | Pressed with click, Enter or Space | `on_press()` |
149
+ | `Checkbox(label, checked)` | Toggle | `on_change(checked)` |
150
+ | `Input(value, placeholder=, password=)` | Single-line text field | `on_change(value)`, `on_submit(value)` |
151
+ | `TextArea(value)` | Multi-line editor | `on_change(value)` |
152
+ | `ListView(items)` | Scrollable list with a highlighted row | `on_select(i, item)`, `on_highlight(i, item)` |
153
+ | `ProgressBar(value)` | `value` between 0 and 1 | |
154
+
155
+ Common widget API: `id=`, `disabled=`, `focusable=`, `mount(*children)`, `remove()`,
156
+ `clear()`, `find(id)`, `get(id, Type)`, `walk()`, `focus()`, `hidden = True`, `bind(key, fn)`,
157
+ `scroll_to()`, and `region` / `content_region` (screen rectangles after layout).
158
+
159
+ ## Events, focus and key bindings
160
+
161
+ - Keys go to the focused widget, then bubble up through its ancestors, then to app bindings.
162
+ Tab / Shift+Tab move focus if nothing handled the key.
163
+ - Mouse events go to the widget under the pointer and bubble up. A press focuses the nearest
164
+ focusable widget, and press+release on the same widget is a click.
165
+ - Key names look like `"a"`, `"A"`, `"space"`, `"enter"`, `"escape"`, `"tab"`, `"shift+tab"`,
166
+ `"up"`, `"pageup"`, `"f5"`, `"ctrl+s"`, `"alt+x"`, `"ctrl+shift+left"`.
167
+
168
+ ```python
169
+ app.bind("ctrl+q", app.exit) # global
170
+ editor.bind("ctrl+s", save) # only while focus is inside `editor`
171
+ app.bind("f1 ctrl+h", lambda: help.set_style(display="flex"))
172
+ ```
173
+
174
+ `ctrl+c` exits by default (`app.unbind("ctrl+c")` to disable). `app.run()` returns the value
175
+ passed to `app.exit(value)`.
176
+
177
+ ## Timers and threads
178
+
179
+ ```python
180
+ timer = app.set_interval(1.0, update_clock) # timer.cancel() to stop
181
+ app.call_later(0.5, lambda: status.set_style(display="none"))
182
+
183
+ def worker(): # in another thread
184
+ result = slow_computation()
185
+ app.call_from_thread(show_result, result) # thread-safe, redraws afterwards
186
+ ```
187
+
188
+ ## Custom widgets
189
+
190
+ Subclass `Widget`, describe the content size, and draw into the canvas:
191
+
192
+ ```python
193
+ from pytui import Style, Widget
194
+
195
+ class Counter(Widget):
196
+ FOCUSABLE = True
197
+ DEFAULT_STYLE = Style(padding=(0, 1), focus=Style(reverse=True))
198
+
199
+ def __init__(self, **kwargs):
200
+ super().__init__(**kwargs)
201
+ self.value = 0
202
+
203
+ def content_width(self) -> int:
204
+ return len(f"count: {self.value}")
205
+
206
+ def content_height(self, width: int) -> int:
207
+ return 1
208
+
209
+ def render(self, canvas):
210
+ area = self.content_region
211
+ canvas.text(area.x, area.y, f"count: {self.value}", self.text_style)
212
+
213
+ def on_key(self, event) -> bool:
214
+ if event.key in ("up", "+"):
215
+ self.value += 1
216
+ return True # handled: stop propagation
217
+ if event.key in ("down", "-"):
218
+ self.value -= 1
219
+ return True
220
+ return False
221
+ ```
222
+
223
+ Background, border, children and clipping are handled for you. Other hooks are `on_mouse`,
224
+ `on_click`, `on_paste`, `on_focus` and `on_blur`.
225
+
226
+ ## Testing your UI
227
+
228
+ No terminal needed: render to text and simulate input.
229
+
230
+ ```python
231
+ def test_login_form():
232
+ name = Input(id="name")
233
+ submitted = []
234
+ app = App(Box(name, Button("Login", on_press=lambda: submitted.append(name.value))))
235
+
236
+ app.render(40, 5)
237
+ app.feed("alice") # raw terminal input: text, escape sequences, mouse reports
238
+ app.press("tab", "enter") # key names
239
+ assert submitted == ["alice"]
240
+ assert "alice" in app.snapshot()
241
+ app.click(0, 1) # mouse click at screen coordinates
242
+ ```
@@ -0,0 +1,46 @@
1
+ [project]
2
+ name = "gdamms-pytui"
3
+ version = "0.2.0"
4
+ description = "Build terminal user interfaces in Python with a flexbox-style layout engine."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ requires-python = ">=3.11"
9
+ dependencies = []
10
+ classifiers = [
11
+ "Development Status :: 3 - Alpha",
12
+ "Environment :: Console :: Curses",
13
+ "Intended Audience :: Developers",
14
+ "Operating System :: POSIX",
15
+ "Programming Language :: Python :: 3",
16
+ "Topic :: Software Development :: User Interfaces",
17
+ "Typing :: Typed",
18
+ ]
19
+
20
+ [[project.authors]]
21
+ name = "gdamms"
22
+ email = "damguillotin@gmail.com"
23
+
24
+ [build-system]
25
+ requires = ["uv_build>=0.12.10,<0.14.0"]
26
+ build-backend = "uv_build"
27
+
28
+ [tool.uv.build-backend]
29
+ module-name = "pytui"
30
+
31
+ [tool.ruff]
32
+ line-length = 100
33
+ target-version = "py311"
34
+
35
+ [tool.ruff.lint]
36
+ select = [
37
+ "E",
38
+ "F",
39
+ "W",
40
+ "I",
41
+ "B",
42
+ "UP",
43
+ ]
44
+
45
+ [dependency-groups]
46
+ dev = ["ruff>=0.6"]
@@ -0,0 +1,38 @@
1
+ [project]
2
+ name = "gdamms-pytui"
3
+ version = "0.2.0"
4
+ description = "Build terminal user interfaces in Python with a flexbox-style layout engine."
5
+ readme = "README.md"
6
+ authors = [{ name = "gdamms", email = "damguillotin@gmail.com" }]
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ requires-python = ">=3.11"
10
+ dependencies = []
11
+ classifiers = [
12
+ "Development Status :: 3 - Alpha",
13
+ "Environment :: Console :: Curses",
14
+ "Intended Audience :: Developers",
15
+ "Operating System :: POSIX",
16
+ "Programming Language :: Python :: 3",
17
+ "Topic :: Software Development :: User Interfaces",
18
+ "Typing :: Typed",
19
+ ]
20
+
21
+ [build-system]
22
+ requires = ["uv_build>=0.12.10,<0.14.0"]
23
+ build-backend = "uv_build"
24
+
25
+ [tool.uv.build-backend]
26
+ module-name = "pytui"
27
+
28
+ [dependency-groups]
29
+ dev = [
30
+ "ruff>=0.6",
31
+ ]
32
+
33
+ [tool.ruff]
34
+ line-length = 100
35
+ target-version = "py311"
36
+
37
+ [tool.ruff.lint]
38
+ select = ["E", "F", "W", "I", "B", "UP"]
@@ -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
+ ]