tuikinter 0.1.0__tar.gz

tuikinter-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE / editor
+.idea/
+.vscode/
+*.swp
+.DS_Store

tuikinter-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-27
+
+### Added
+- Initial release.
+- `tkinter`-style imperative façade over [Textual](https://github.com/Textualize/textual).
+- Root window `Tk` with `title()`, `mainloop()`, `destroy()`, `after()`, `every()`.
+- Widgets: `Frame`, `Label`, `Button`, `Entry`, `Text`, `Checkbutton`, `Listbox`, `Progressbar`.
+- Observable variables `StringVar`, `IntVar`, `BooleanVar` with two-way binding and `trace_add`.
+- Layout managers: `pack()` (primary) and `grid()` (best-effort).
+- `config()` / `configure()` and dict-style `widget["key"] = value` configuration.
+- `command=` callback routing via Textual's message system.
+- Headless test suite driven by Textual's `Pilot` harness.
+
+[Unreleased]: https://github.com/joshuamaojh/tuikinter/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/joshuamaojh/tuikinter/releases/tag/v0.1.0

tuikinter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Mao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tuikinter-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: tuikinter
+Version: 0.1.0
+Summary: Write terminal UIs with a tkinter/PyQt-style imperative API, powered by Textual.
+Project-URL: Homepage, https://github.com/joshuamaojh/tuikinter
+Project-URL: Repository, https://github.com/joshuamaojh/tuikinter
+Project-URL: Issues, https://github.com/joshuamaojh/tuikinter/issues
+Project-URL: Changelog, https://github.com/joshuamaojh/tuikinter/blob/main/CHANGELOG.md
+Author: Joshua Mao
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,console,terminal,textual,tkinter,tui,ui,widgets
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.9
+Requires-Dist: textual>=0.40
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tuikinter
+
+**Write terminal UIs (TUIs) with a `tkinter` / `PyQt`-style imperative API — powered by [Textual](https://github.com/Textualize/textual).**
+
+Textual is a fantastic, modern TUI framework, but its programming model is *declarative and async*: you `yield` widgets inside `App.compose()`, style them with TCSS, and manage state with reactives. If your mental model is `tkinter` — *create widgets one by one, lay them out with `pack` / `grid`, then call `mainloop()`* — `tuikinter` gives you exactly that, while Textual does the heavy lifting underneath.
+
+```python
+import tuikinter as tk
+
+root = tk.Tk()
+root.title("Hello")
+
+name = tk.StringVar(root, value="World")
+tk.Label(root, text="Name:").pack(side="left")
+tk.Entry(root, textvariable=name).pack(side="left", fill="x", expand=True)
+
+tk.Button(root, text="Greet", command=lambda: print(f"Hi {name.get()}")).pack()
+tk.Button(root, text="Quit", command=root.destroy).pack()
+
+root.mainloop()
+```
+
+## Why
+
+If you already know `tkinter`, you already know `tuikinter`. The API mirrors it closely — same widget names, same `pack`/`grid`, same `StringVar`/`IntVar`/`BooleanVar` with `trace_add`, same `command=` callbacks, same `widget.config(...)` and `widget["text"] = ...`. You get a real, keyboard-navigable terminal app (and, because it's Textual underneath, it can even run in a browser via `textual serve`).
+
+## Install
+
+```bash
+pip install tuikinter
+```
+
+Requires Python 3.9+. Textual is pulled in automatically.
+
+## How it works
+
+A façade in two phases:
+
+1. **Build phase** (before `mainloop()`): each widget you create is a lightweight *spec proxy* that records which Textual widget to use, its options, callbacks, and layout intent, attaching itself to its parent to form a tree.
+2. **Run phase** (`mainloop()`): a Textual `App` subclass is generated on the fly. Its `compose()` walks the tree and instantiates the real Textual widgets; `pack`/`grid` are translated into containers (`Vertical` / `Horizontal` / `Grid`) plus styles; callbacks are routed back to your plain functions through Textual's message system.
+
+This is the same trick `tkinter` itself uses behind the scenes with Tcl commands.
+
+## Widgets
+
+| tuikinter | maps to (Textual) | notes |
+|-----------|-------------------|-------|
+| `Tk` | `App` | root window; call `.mainloop()` |
+| `Frame` | `Vertical` / `Horizontal` / `Grid` | container; nest for complex layouts |
+| `Label` | `Static` | `config(text=...)` to update |
+| `Button` | `Button` | `command=fn`; `variant="success"/"error"/...` |
+| `Entry` | `Input` | `textvariable=`, `get()`, `insert()`, `delete()`, `show="*"` |
+| `Text` | `TextArea` | multi-line |
+| `Checkbutton` | `Checkbox` | `variable=BooleanVar`, `command=fn` |
+| `Listbox` | `OptionList` | `values=[...]`, `insert()`, `get_selected()` |
+| `Progressbar` | `ProgressBar` | `maximum=`, `set()`, `step()` |
+
+## Variables
+
+```python
+name = tk.StringVar(root, value="Joshua")
+name.trace_add("write", lambda: print("changed to", name.get()))
+name.set("World")          # pushes to any bound Entry + fires traces
+```
+
+`StringVar`, `IntVar`, and `BooleanVar` bind two-way to `Entry` / `Checkbutton`.
+
+## Layout
+
+`pack()` is the primary, robust layout manager:
+
+```python
+tk.Label(root, text="Top").pack(side="top", fill="x")
+tk.Button(root, text="Left").pack(side="left", padx=1)
+tk.Entry(root).pack(side="left", fill="x", expand=True)
+```
+
+`grid()` is supported on a best-effort basis (terminal grid semantics differ from pixel grids):
+
+```python
+grid = tk.Frame(root); grid.pack()
+for i, t in enumerate("789456123"):
+    tk.Button(grid, text=t).grid(row=i // 3, column=i % 3)
+tk.Button(grid, text="0").grid(row=3, column=0, columnspan=3)
+```
+
+## Timers
+
+```python
+root.after(1000, lambda: print("once, after 1s"))
+root.every(1000, lambda: clock.config(text=time.strftime("%H:%M:%S")))
+```
+
+## Limitations / honest notes
+
+- **`pack` is the robust path; `grid` is best-effort.** For non-trivial layouts, nest `Frame`s (just like idiomatic `tkinter`) rather than mixing `side`s in one frame.
+- Colors and sizes use **Textual semantics** (color names, `"100%"`, `"1fr"`), not pixels.
+- An `Entry` bound to a `textvariable` fires its trace once on mount (Textual emits a `Changed` event when the `Input` first appears). Usually harmless — worth knowing if your trace has side effects.
+- Dynamically creating + packing widgets *after* `mainloop()` has started is best-effort.
+
+## Development
+
+```bash
+git clone https://github.com/joshuamaojh/tuikinter
+cd tuikinter
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Tests drive the app headlessly with Textual's `Pilot` harness.
+
+## License
+
+MIT © Joshua Mao
+
+---
+
+## 中文简述
+
+`tuikinter` 让你用 **`tkinter` / `PyQt` 那样的命令式写法**来写终端 TUI，底层由 Textual 驱动。会 `tkinter` 就会它：控件名、`pack`/`grid`、`StringVar`/`IntVar`/`BooleanVar`（带 `trace_add`）、`command=` 回调、`config()` / `widget["text"]=...` 都一致。
+
+```python
+import tuikinter as tk
+root = tk.Tk()
+tk.Label(root, text="你好").pack()
+tk.Button(root, text="退出", command=root.destroy).pack()
+root.mainloop()
+```
+
+几个要点：`pack` 最稳，复杂布局请像 tkinter 那样嵌套 `Frame`；颜色/尺寸走 Textual 语义（色名、`"100%"`、`"1fr"`），不是像素。

tuikinter-0.1.0/README.md

@@ -0,0 +1,131 @@
+# tuikinter
+
+**Write terminal UIs (TUIs) with a `tkinter` / `PyQt`-style imperative API — powered by [Textual](https://github.com/Textualize/textual).**
+
+Textual is a fantastic, modern TUI framework, but its programming model is *declarative and async*: you `yield` widgets inside `App.compose()`, style them with TCSS, and manage state with reactives. If your mental model is `tkinter` — *create widgets one by one, lay them out with `pack` / `grid`, then call `mainloop()`* — `tuikinter` gives you exactly that, while Textual does the heavy lifting underneath.
+
+```python
+import tuikinter as tk
+
+root = tk.Tk()
+root.title("Hello")
+
+name = tk.StringVar(root, value="World")
+tk.Label(root, text="Name:").pack(side="left")
+tk.Entry(root, textvariable=name).pack(side="left", fill="x", expand=True)
+
+tk.Button(root, text="Greet", command=lambda: print(f"Hi {name.get()}")).pack()
+tk.Button(root, text="Quit", command=root.destroy).pack()
+
+root.mainloop()
+```
+
+## Why
+
+If you already know `tkinter`, you already know `tuikinter`. The API mirrors it closely — same widget names, same `pack`/`grid`, same `StringVar`/`IntVar`/`BooleanVar` with `trace_add`, same `command=` callbacks, same `widget.config(...)` and `widget["text"] = ...`. You get a real, keyboard-navigable terminal app (and, because it's Textual underneath, it can even run in a browser via `textual serve`).
+
+## Install
+
+```bash
+pip install tuikinter
+```
+
+Requires Python 3.9+. Textual is pulled in automatically.
+
+## How it works
+
+A façade in two phases:
+
+1. **Build phase** (before `mainloop()`): each widget you create is a lightweight *spec proxy* that records which Textual widget to use, its options, callbacks, and layout intent, attaching itself to its parent to form a tree.
+2. **Run phase** (`mainloop()`): a Textual `App` subclass is generated on the fly. Its `compose()` walks the tree and instantiates the real Textual widgets; `pack`/`grid` are translated into containers (`Vertical` / `Horizontal` / `Grid`) plus styles; callbacks are routed back to your plain functions through Textual's message system.
+
+This is the same trick `tkinter` itself uses behind the scenes with Tcl commands.
+
+## Widgets
+
+| tuikinter | maps to (Textual) | notes |
+|-----------|-------------------|-------|
+| `Tk` | `App` | root window; call `.mainloop()` |
+| `Frame` | `Vertical` / `Horizontal` / `Grid` | container; nest for complex layouts |
+| `Label` | `Static` | `config(text=...)` to update |
+| `Button` | `Button` | `command=fn`; `variant="success"/"error"/...` |
+| `Entry` | `Input` | `textvariable=`, `get()`, `insert()`, `delete()`, `show="*"` |
+| `Text` | `TextArea` | multi-line |
+| `Checkbutton` | `Checkbox` | `variable=BooleanVar`, `command=fn` |
+| `Listbox` | `OptionList` | `values=[...]`, `insert()`, `get_selected()` |
+| `Progressbar` | `ProgressBar` | `maximum=`, `set()`, `step()` |
+
+## Variables
+
+```python
+name = tk.StringVar(root, value="Joshua")
+name.trace_add("write", lambda: print("changed to", name.get()))
+name.set("World")          # pushes to any bound Entry + fires traces
+```
+
+`StringVar`, `IntVar`, and `BooleanVar` bind two-way to `Entry` / `Checkbutton`.
+
+## Layout
+
+`pack()` is the primary, robust layout manager:
+
+```python
+tk.Label(root, text="Top").pack(side="top", fill="x")
+tk.Button(root, text="Left").pack(side="left", padx=1)
+tk.Entry(root).pack(side="left", fill="x", expand=True)
+```
+
+`grid()` is supported on a best-effort basis (terminal grid semantics differ from pixel grids):
+
+```python
+grid = tk.Frame(root); grid.pack()
+for i, t in enumerate("789456123"):
+    tk.Button(grid, text=t).grid(row=i // 3, column=i % 3)
+tk.Button(grid, text="0").grid(row=3, column=0, columnspan=3)
+```
+
+## Timers
+
+```python
+root.after(1000, lambda: print("once, after 1s"))
+root.every(1000, lambda: clock.config(text=time.strftime("%H:%M:%S")))
+```
+
+## Limitations / honest notes
+
+- **`pack` is the robust path; `grid` is best-effort.** For non-trivial layouts, nest `Frame`s (just like idiomatic `tkinter`) rather than mixing `side`s in one frame.
+- Colors and sizes use **Textual semantics** (color names, `"100%"`, `"1fr"`), not pixels.
+- An `Entry` bound to a `textvariable` fires its trace once on mount (Textual emits a `Changed` event when the `Input` first appears). Usually harmless — worth knowing if your trace has side effects.
+- Dynamically creating + packing widgets *after* `mainloop()` has started is best-effort.
+
+## Development
+
+```bash
+git clone https://github.com/joshuamaojh/tuikinter
+cd tuikinter
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Tests drive the app headlessly with Textual's `Pilot` harness.
+
+## License
+
+MIT © Joshua Mao
+
+---
+
+## 中文简述
+
+`tuikinter` 让你用 **`tkinter` / `PyQt` 那样的命令式写法**来写终端 TUI，底层由 Textual 驱动。会 `tkinter` 就会它：控件名、`pack`/`grid`、`StringVar`/`IntVar`/`BooleanVar`（带 `trace_add`）、`command=` 回调、`config()` / `widget["text"]=...` 都一致。
+
+```python
+import tuikinter as tk
+root = tk.Tk()
+tk.Label(root, text="你好").pack()
+tk.Button(root, text="退出", command=root.destroy).pack()
+root.mainloop()
+```
+
+几个要点：`pack` 最稳，复杂布局请像 tkinter 那样嵌套 `Frame`；颜色/尺寸走 Textual 语义（色名、`"100%"`、`"1fr"`），不是像素。

tuikinter-0.1.0/examples/demo.py

@@ -0,0 +1,74 @@
+"""
+tuikinter 演示 —— 写法跟 tkinter 几乎一模一样。
+在真终端里运行:  python examples/demo.py   (q 或点 Quit 退出)
+"""
+import time
+import tuikinter as tk
+
+root = tk.Tk()
+root.title("tuikinter demo —— 像 tkinter 一样写 TUI")
+
+# ── 顶部: 实时时钟(用 every 周期刷新)──────────────────
+clock = tk.Label(root, text="")
+clock.pack(fill="x", pady=1)
+
+
+def tick():
+    clock.config(text=f"  现在时间  {time.strftime('%Y-%m-%d %H:%M:%S')}")
+
+
+root.every(1000, tick)   # 每秒刷新
+tick()
+
+# ── 计数器 ───────────────────────────────────
+counter_box = tk.Frame(root)
+counter_box.pack(fill="x", pady=1)
+
+count = tk.IntVar(root, value=0)
+count_label = tk.Label(counter_box, text="计数: 0")
+count_label.pack(side="left", padx=2)
+
+
+def bump(delta):
+    count.set(count.get() + delta)
+    count_label.config(text=f"计数: {count.get()}")
+
+
+tk.Button(counter_box, text="-1", variant="error",
+          command=lambda: bump(-1)).pack(side="left", padx=1)
+tk.Button(counter_box, text="+1", variant="success",
+          command=lambda: bump(+1)).pack(side="left", padx=1)
+
+# ── 表单: Entry + StringVar 双向绑定, 实时镜像到下面的 Label ────────
+form = tk.Frame(root)
+form.pack(fill="x", pady=1)
+
+tk.Label(form, text="你的名字:").pack(side="left", padx=1)
+name = tk.StringVar(root, value="Joshua")
+tk.Entry(form, textvariable=name, placeholder="在这里输入...").pack(
+    side="left", fill="x", expand=True, padx=1)
+
+mirror = tk.Label(root, text="")
+mirror.pack(fill="x")
+# trace: 变量一变, 自动更新镜像 Label —— 不用手动刷新
+name.trace_add("write", lambda: mirror.config(text=f"  你好, {name.get()}！"))
+mirror.config(text=f"  你好, {name.get()}！")
+
+# ── 勾选框 + 进度条联动 ───────────────────────────
+agree = tk.BooleanVar(root, value=False)
+bar = tk.Progressbar(root, maximum=100)
+bar.pack(fill="x", pady=1)
+
+
+def on_toggle():
+    bar.set(100 if agree.get() else 0)
+
+
+tk.Checkbutton(root, text="勾上把进度条拉满", variable=agree,
+               command=on_toggle).pack()
+
+# ── 退出按钮 ────────────────────────────────
+tk.Button(root, text="Quit", command=root.destroy).pack(pady=1)
+
+if __name__ == "__main__":
+    root.mainloop()

tuikinter-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tuikinter"
+dynamic = ["version"]
+description = "Write terminal UIs with a tkinter/PyQt-style imperative API, powered by Textual."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Joshua Mao" }]
+keywords = ["tui", "terminal", "textual", "tkinter", "ui", "cli", "widgets", "console"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: User Interfaces",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "textual>=0.40",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-asyncio>=0.21",
+    "build",
+    "twine",
+]
+
+[project.urls]
+Homepage = "https://github.com/joshuamaojh/tuikinter"
+Repository = "https://github.com/joshuamaojh/tuikinter"
+Issues = "https://github.com/joshuamaojh/tuikinter/issues"
+Changelog = "https://github.com/joshuamaojh/tuikinter/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/tuikinter/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tuikinter"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src",
+    "tests",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

tuikinter-0.1.0/src/tuikinter/__init__.py

@@ -0,0 +1,88 @@
+"""
+tuikinter —— 用 tkinter / PyQt 那样的命令式 API 写终端 TUI，底层由 Textual 驱动。
+
+快速上手::
+
+    import tuikinter as tk
+
+    root = tk.Tk()
+    root.title("Hello")
+
+    tk.Label(root, text="名字:").pack(side="left")
+    name = tk.StringVar(root, value="World")
+    tk.Entry(root, textvariable=name).pack(side="left", fill="x", expand=True)
+
+    tk.Button(root, text="退出", command=root.destroy).pack()
+    root.mainloop()
+
+更多见 README 与 examples/demo.py。
+"""
+
+from .core import (
+    Tk,
+    Frame,
+    Label,
+    Button,
+    Entry,
+    Text,
+    Checkbutton,
+    Listbox,
+    Progressbar,
+    Widget,
+    Variable,
+    StringVar,
+    IntVar,
+    BooleanVar,
+    TOP,
+    BOTTOM,
+    LEFT,
+    RIGHT,
+    X,
+    Y,
+    BOTH,
+    END,
+    NORMAL,
+    DISABLED,
+    W,
+    E,
+    N,
+    S,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # 根窗口与控件
+    "Tk",
+    "Frame",
+    "Label",
+    "Button",
+    "Entry",
+    "Text",
+    "Checkbutton",
+    "Listbox",
+    "Progressbar",
+    "Widget",
+    # 变量
+    "Variable",
+    "StringVar",
+    "IntVar",
+    "BooleanVar",
+    # 常量
+    "TOP",
+    "BOTTOM",
+    "LEFT",
+    "RIGHT",
+    "X",
+    "Y",
+    "BOTH",
+    "END",
+    "NORMAL",
+    "DISABLED",
+    "W",
+    "E",
+    "N",
+    "S",
+    # 元信息
+    "__version__",
+]

tuikinter-0.1.0/src/tuikinter/core.py

@@ -0,0 +1,553 @@
+"""
+tuikinter.core —— 实现主体。
+
+设计思路(facade 模式):
+    Textual 本身是「声明式 + 异步」的: 你在 App.compose() 里 yield 组件,用 TCSS 写样式,
+    用 reactive 管状态。这跟 tkinter「先逐个 new 出控件、pack/grid 布局、最后 mainloop()」
+    的命令式手感完全相反。本模块在中间加一层翻译:
+
+      1. 建树期(mainloop 之前): 每个控件其实是一个「规格代理」, 记录要用哪个 Textual 控件、
+         参数、回调、布局意图, 并挂到父节点的 children 上, 形成一棵树。
+      2. 运行期(mainloop 时): 动态生成一个 Textual App 子类, 它的 compose() 遍历这棵树、
+         把真正的 Textual 控件造出来 yield 出去; 布局意图翻译成容器(Vertical/Horizontal/
+         Grid) + styles; 回调通过 Textual 的消息系统路由回你注册的普通函数。
+
+    这跟 tkinter 背后用 Tcl 命令是同一个套路。
+"""
+
+from __future__ import annotations
+
+# ---- tkinter 风格常量 -------------------------------------------------------
+TOP, BOTTOM, LEFT, RIGHT = "top", "bottom", "left", "right"
+X, Y, BOTH = "x", "y", "both"
+END = "end"
+NORMAL, DISABLED = "normal", "disabled"
+W, E, N, S = "w", "e", "n", "s"
+
+
+# ---- 布局翻译 ---------------------------------------------------------------
+def _apply_pack_layout(child: "Widget", w, horizontal: bool) -> None:
+    """把一个 pack 进容器的子控件的布局意图翻译成 Textual styles。"""
+    lay = child._layout
+    padx, pady = lay.get("padx", 0), lay.get("pady", 0)
+    if padx or pady:
+        w.styles.margin = (pady, padx, pady, padx)
+    fill, expand, side = lay.get("fill"), lay.get("expand", False), lay.get("side", TOP)
+    if horizontal:
+        if fill in (Y, BOTH):
+            w.styles.height = "100%"
+        if expand or fill == BOTH:
+            w.styles.width = "1fr"
+        else:
+            # 否则缩到内容宽度, 避免某些控件(如 Static)默认抢占 1fr
+            w.styles.width = "auto"
+        if side == RIGHT:
+            w.styles.dock = "right"
+    else:
+        if fill in (X, BOTH):
+            w.styles.width = "100%"
+        if expand or fill == BOTH:
+            w.styles.height = "1fr"
+        else:
+            w.styles.height = "auto"
+        if side == BOTTOM:
+            w.styles.dock = "bottom"
+
+
+def _build_container(node, cid: str):
+    """把 node(根或 Frame)的已布局子控件造成一个 Textual 容器。"""
+    from textual.containers import Vertical, Horizontal, Grid
+
+    placed = [c for c in node.children if c._layout is not None]
+    use_grid = any(c._layout.get("_mgr") == "grid" for c in placed)
+
+    if use_grid:
+        cols = max((c._layout.get("column", 0) + c._layout.get("columnspan", 1)
+                    for c in placed), default=1)
+        rows = max((c._layout.get("row", 0) + c._layout.get("rowspan", 1)
+                    for c in placed), default=1)
+        from textual.widgets import Static
+        cells = [Static("") for _ in range(cols * rows)]
+        for c in placed:
+            idx = c._layout.get("row", 0) * cols + c._layout.get("column", 0)
+            built = c._build()
+            if 0 <= idx < len(cells):
+                cells[idx] = built
+        return Grid(*cells, id=cid)
+
+    horizontal = any(c._layout.get("side") in (LEFT, RIGHT) for c in placed)
+    built = []
+    for c in placed:
+        w = c._build()
+        _apply_pack_layout(c, w, horizontal)
+        built.append(w)
+    Cont = Horizontal if horizontal else Vertical
+    return Cont(*built, id=cid)
+
+
+def _collect_grid_css(node, cid: str, out: list) -> None:
+    """grid 容器的 layout/grid-size 必须走 CSS, 在建 App 前预扫描收集。"""
+    placed = [c for c in node.children if c._layout is not None]
+    if any(c._layout.get("_mgr") == "grid" for c in placed):
+        cols = max((c._layout.get("column", 0) + c._layout.get("columnspan", 1)
+                    for c in placed), default=1)
+        rows = max((c._layout.get("row", 0) + c._layout.get("rowspan", 1)
+                    for c in placed), default=1)
+        out.append(f"#{cid} {{ layout: grid; grid-size: {cols} {rows}; grid-gutter: 0 1; }}")
+        for c in placed:
+            cs, rs = c._layout.get("columnspan", 1), c._layout.get("rowspan", 1)
+            if cs > 1 or rs > 1:
+                out.append(f"#{c._cid} {{ column-span: {cs}; row-span: {rs}; }}")
+    for c in node.children:
+        if isinstance(c, Frame):
+            _collect_grid_css(c, c._cid, out)
+
+
+# ---- 变量(StringVar / IntVar / BooleanVar)----------------------------------
+class Variable:
+    """tkinter 风格的可观察变量, 支持与 Entry/Checkbutton 双向绑定 + trace 回调。"""
+
+    def __init__(self, master=None, value=""):
+        self._value = value
+        self._entries = []     # 绑定的 Entry
+        self._checks = []      # 绑定的 Checkbutton
+        self._traces = []      # 回调列表
+
+    def get(self):
+        return self._value
+
+    def set(self, value):
+        self._value = value
+        for e in self._entries:
+            e._set_live_value(value)
+        for c in self._checks:
+            c._set_live_value(value)
+        self._fire()
+
+    def trace_add(self, mode, callback):
+        self._traces.append(callback)
+        return callback
+    trace = trace_add  # 兼容老 tkinter 写法
+
+    # --- 内部 ---
+    def _fire(self):
+        for cb in self._traces:
+            try:
+                cb()
+            except TypeError:
+                cb(None, None, "write")
+
+    def _bind_entry(self, e):
+        self._entries.append(e)
+
+    def _bind_check(self, c):
+        self._checks.append(c)
+
+    def _update_from_widget(self, value):
+        self._value = value
+        self._fire()
+
+
+class StringVar(Variable):
+    def __init__(self, master=None, value=""):
+        super().__init__(master, str(value))
+
+
+class IntVar(Variable):
+    def __init__(self, master=None, value=0):
+        super().__init__(master, int(value))
+
+    def _update_from_widget(self, value):
+        try:
+            self._value = int(value)
+        except (ValueError, TypeError):
+            self._value = 0
+        self._fire()
+
+
+class BooleanVar(Variable):
+    def __init__(self, master=None, value=False):
+        super().__init__(master, bool(value))
+
+
+# ---- 控件基类 ---------------------------------------------------------------
+class Widget:
+    """所有控件的基类: 负责挂树、分配 id、存参数/布局, 以及运行期把配置转发给真控件。"""
+
+    def __init__(self, master, **opts):
+        if master is None:
+            raise ValueError("控件必须有 master(父容器或根窗口)")
+        self.master = master
+        self.root = master.root
+        self.children = []
+        master.children.append(self)
+        self._opts = dict(opts)
+        self._command = opts.get("command")
+        self._layout = None          # pack/grid 后才有
+        self._widget = None          # 运行期的真 Textual 控件
+        self._suppress = False       # 防双向绑定回环
+        self._cid = self.root._newid()
+
+    # --- 布局 ---
+    def pack(self, side=TOP, fill=None, expand=False, padx=0, pady=0, **_):
+        self._layout = dict(_mgr="pack", side=side, fill=fill,
+                            expand=expand, padx=padx, pady=pady)
+        if self.root._running:
+            self._mount_live()
+        return self
+
+    def grid(self, row=0, column=0, columnspan=1, rowspan=1,
+             sticky=None, padx=0, pady=0, **_):
+        self._layout = dict(_mgr="grid", row=row, column=column,
+                            columnspan=columnspan, rowspan=rowspan,
+                            sticky=sticky, padx=padx, pady=pady)
+        return self
+
+    def place(self, **kw):  # 终端没有绝对坐标, 退化成 pack
+        return self.pack()
+
+    # --- 配置(tkinter 的 config / 字典访问)---
+    def config(self, **opts):
+        for k, v in opts.items():
+            self._opts[k] = v
+            if k == "command":
+                self._command = v
+            else:
+                self._apply(k, v)
+        return self
+    configure = config
+
+    def __setitem__(self, key, value):
+        self.config(**{key: value})
+
+    def __getitem__(self, key):
+        return self._opts.get(key)
+
+    def cget(self, key):
+        return self._opts.get(key)
+
+    # --- 子类可覆写 ---
+    def _create_textual(self):
+        raise NotImplementedError
+
+    def _apply_text(self, value):
+        pass
+
+    def _apply(self, key, value):
+        """运行期把通用配置转发到真控件的 styles。"""
+        w = self._widget
+        if key in ("text", "label"):
+            self._apply_text(value)
+            return
+        if w is None:
+            return
+        if key in ("fg", "foreground", "color"):
+            w.styles.color = value
+        elif key in ("bg", "background"):
+            w.styles.background = value
+        elif key == "width":
+            w.styles.width = value
+        elif key == "height":
+            w.styles.height = value
+        elif key == "state":
+            w.disabled = (value == DISABLED)
+        elif key == "disabled":
+            w.disabled = bool(value)
+
+    # --- 内部: 造真控件 + 套上存好的样式 ---
+    def _build(self):
+        w = self._create_textual()
+        self.root._by_id[self._cid] = self
+        self._widget = w
+        o = self._opts
+        for k in ("fg", "foreground", "color", "bg", "background",
+                  "width", "height", "state", "disabled"):
+            if k in o:
+                self._apply(k, o[k])
+        return w
+
+    def _mount_live(self):
+        """运行期动态 pack: best-effort 直接挂到父控件下。"""
+        try:
+            parent = self.master._widget if isinstance(self.master, Widget) \
+                else self.root._app.screen
+            parent.mount(self._build())
+        except Exception:
+            pass
+
+
+# ---- 容器 -------------------------------------------------------------------
+class Frame(Widget):
+    """容器, 对应 Textual 的 Vertical/Horizontal/Grid。子控件 pack/grid 到它里面。"""
+
+    def _create_textual(self):
+        return _build_container(self, self._cid)
+
+
+# ---- 文本类 -----------------------------------------------------------------
+class Label(Widget):
+    def _create_textual(self):
+        from textual.widgets import Static
+        return Static(str(self._opts.get("text", "")), id=self._cid)
+
+    def _apply_text(self, value):
+        if self._widget is not None:
+            self._widget.update(str(value))
+
+
+class Button(Widget):
+    def _create_textual(self):
+        from textual.widgets import Button as TButton
+        return TButton(str(self._opts.get("text", "Button")),
+                       variant=self._opts.get("variant", "default"),
+                       id=self._cid)
+
+    def _apply_text(self, value):
+        if self._widget is not None:
+            self._widget.label = str(value)
+
+
+class Entry(Widget):
+    def _create_textual(self):
+        from textual.widgets import Input
+        var = self._opts.get("textvariable")
+        init = var.get() if var is not None else self._opts.get("text", "")
+        w = Input(value=str(init),
+                  placeholder=self._opts.get("placeholder", ""),
+                  password=self._opts.get("show") == "*",
+                  id=self._cid)
+        if var is not None:
+            var._bind_entry(self)
+        return w
+
+    def get(self):
+        if self._widget is not None:
+            return self._widget.value
+        var = self._opts.get("textvariable")
+        return var.get() if var is not None else self._opts.get("text", "")
+
+    def set(self, value):
+        self._opts["text"] = value
+        self._set_live_value(value)
+
+    def insert(self, index, s):
+        cur = self.get()
+        if index in (END, "end") or (isinstance(index, int) and index >= len(cur)):
+            self.set(cur + s)
+        else:
+            self.set(cur[:index] + s + cur[index:])
+
+    def delete(self, first, last=None):
+        cur = self.get()
+        if first in (0, "0") and last in (END, "end", None):
+            self.set("")
+        else:
+            last = len(cur) if last in (END, "end", None) else last
+            self.set(cur[:first] + cur[last:])
+
+    def _set_live_value(self, value):
+        if self._widget is not None:
+            self._suppress = True
+            self._widget.value = str(value)
+            self._suppress = False
+
+
+class Text(Widget):
+    """多行文本框, 对应 Textual TextArea。"""
+
+    def _create_textual(self):
+        from textual.widgets import TextArea
+        return TextArea(text=str(self._opts.get("text", "")), id=self._cid)
+
+    def get(self, *a):
+        return self._widget.text if self._widget is not None else self._opts.get("text", "")
+
+    def insert(self, index, s):
+        if self._widget is not None:
+            self._widget.text = self._widget.text + s
+        else:
+            self._opts["text"] = self._opts.get("text", "") + s
+
+    def delete(self, *a):
+        if self._widget is not None:
+            self._widget.text = ""
+        else:
+            self._opts["text"] = ""
+
+
+# ---- 选择类 -----------------------------------------------------------------
+class Checkbutton(Widget):
+    def _create_textual(self):
+        from textual.widgets import Checkbox
+        var = self._opts.get("variable")
+        init = bool(var.get()) if var is not None else bool(self._opts.get("value", False))
+        w = Checkbox(str(self._opts.get("text", "")), value=init, id=self._cid)
+        if var is not None:
+            var._bind_check(self)
+        return w
+
+    def get(self):
+        if self._widget is not None:
+            return self._widget.value
+        var = self._opts.get("variable")
+        return bool(var.get()) if var is not None else bool(self._opts.get("value", False))
+
+    def _set_live_value(self, value):
+        if self._widget is not None:
+            self._suppress = True
+            self._widget.value = bool(value)
+            self._suppress = False
+
+
+class Listbox(Widget):
+    """列表框, 对应 Textual OptionList。选中项变化触发 command。"""
+
+    def _create_textual(self):
+        from textual.widgets import OptionList
+        items = [str(i) for i in self._opts.get("values", [])]
+        return OptionList(*items, id=self._cid)
+
+    def insert(self, index, *items):
+        for it in items:
+            if self._widget is not None:
+                self._widget.add_option(str(it))
+            else:
+                self._opts.setdefault("values", []).append(it)
+
+    def get_selected(self):
+        if self._widget is not None and self._widget.highlighted is not None:
+            return self._widget.get_option_at_index(self._widget.highlighted).prompt
+        return None
+
+
+# ---- 进度条 -----------------------------------------------------------------
+class Progressbar(Widget):
+    def _create_textual(self):
+        from textual.widgets import ProgressBar
+        return ProgressBar(total=self._opts.get("maximum", 100),
+                           show_eta=False, id=self._cid)
+
+    def set(self, value):
+        self._opts["value"] = value
+        if self._widget is not None:
+            self._widget.update(progress=value)
+
+    def step(self, delta=1):
+        self.set(self._opts.get("value", 0) + delta)
+
+
+# ---- 根窗口 -----------------------------------------------------------------
+class Tk:
+    """根窗口, 对应 Textual App。建好整棵控件树后调用 mainloop() 启动。"""
+
+    def __init__(self, screen_name=None):
+        self.root = self
+        self.children = []
+        self._by_id = {}
+        self._counter = 0
+        self._title = ""
+        self._css = ""
+        self._timers = []      # mainloop 前排队的 after/every
+        self._app = None
+        self._running = False
+
+    def _newid(self):
+        self._counter += 1
+        return f"w{self._counter}"
+
+    # --- tkinter 风格窗口方法 ---
+    def title(self, text):
+        self._title = text
+        if self._app is not None:
+            self._app.title = text
+        return self
+
+    def geometry(self, *a):     # 终端尺寸固定, 忽略
+        return self
+
+    def after(self, ms, func):
+        if self._running and self._app is not None:
+            self._app.set_timer(ms / 1000, func)
+        else:
+            self._timers.append((ms / 1000, func, False))
+
+    def every(self, ms, func):  # 周期定时器(tkinter 要手动重排, 这里直接给个便捷版)
+        if self._running and self._app is not None:
+            self._app.set_interval(ms / 1000, func)
+        else:
+            self._timers.append((ms / 1000, func, True))
+
+    def destroy(self):
+        if self._app is not None:
+            self._app.exit()
+    quit = destroy
+
+    # --- 生命周期 ---
+    def _build_app(self):
+        css_lines = []
+        _collect_grid_css(self, "_root", css_lines)
+        self._css = "\n".join(css_lines)
+        return _make_app_class(self)()
+
+    def mainloop(self):
+        self._app = self._build_app()
+        self._app.run()
+    run = mainloop
+
+
+# ---- 动态生成 Textual App 子类 ----------------------------------------------
+def _make_app_class(root: Tk):
+    from textual.app import App
+    from textual.widgets import Button, Input, Checkbox, OptionList
+
+    class _TkApp(App):
+        CSS = root._css
+
+        def compose(self):
+            yield _build_container(root, "_root")
+
+        def on_mount(self):
+            root._running = True
+            if root._title:
+                self.title = root._title
+            for delay, cb, repeat in root._timers:
+                (self.set_interval if repeat else self.set_timer)(delay, cb)
+
+        def on_unmount(self):
+            root._running = False
+
+        # --- 消息 -> 回调路由 ---
+        def on_button_pressed(self, event: Button.Pressed):
+            w = root._by_id.get(event.button.id)
+            if w is not None and w._command is not None:
+                w._command()
+
+        def on_input_changed(self, event: Input.Changed):
+            w = root._by_id.get(event.input.id)
+            if w is None or getattr(w, "_suppress", False):
+                return
+            var = w._opts.get("textvariable")
+            if var is not None:
+                var._update_from_widget(event.value)
+
+        def on_input_submitted(self, event: Input.Submitted):
+            w = root._by_id.get(event.input.id)
+            if w is not None and w._command is not None:
+                w._command()
+
+        def on_checkbox_changed(self, event: Checkbox.Changed):
+            w = root._by_id.get(event.checkbox.id)
+            if w is None:
+                return
+            var = w._opts.get("variable")
+            if var is not None and not getattr(w, "_suppress", False):
+                var._update_from_widget(event.value)
+            if w._command is not None:
+                w._command()
+
+        def on_option_list_option_selected(self, event: OptionList.OptionSelected):
+            w = root._by_id.get(event.option_list.id)
+            if w is not None and w._command is not None:
+                w._command()
+
+    return _TkApp

tuikinter-0.1.0/tests/test_tuikinter.py

@@ -0,0 +1,122 @@
+"""tuikinter 的无头测试 —— 用 Textual 的 Pilot 真跑交互。"""
+import pytest
+
+import tuikinter as tk
+
+
+def _build_form():
+    """搭一套包含各类控件的小表单, 返回 (root, handles)。"""
+    root = tk.Tk()
+    root.title("test")
+    state = {"clicks": 0, "checked": None, "traced": []}
+
+    lab = tk.Label(root, text="hello")
+    lab.pack(pady=1)
+
+    def on_click():
+        state["clicks"] += 1
+        lab.config(text=f"clicked {state['clicks']}")
+
+    btn = tk.Button(root, text="go", command=on_click)
+    btn.pack()
+
+    sv = tk.StringVar(root, value="init")
+    sv.trace_add("write", lambda: state["traced"].append(sv.get()))
+    ent = tk.Entry(root, textvariable=sv)
+    ent.pack(fill="x")
+
+    bv = tk.BooleanVar(root, value=False)
+
+    def on_check():
+        state["checked"] = bv.get()
+
+    chk = tk.Checkbutton(root, text="agree", variable=bv, command=on_check)
+    chk.pack()
+
+    pb = tk.Progressbar(root, maximum=100)
+    pb.pack(fill="x")
+
+    return root, dict(lab=lab, btn=btn, ent=ent, sv=sv, bv=bv, chk=chk, pb=pb,
+                      state=state)
+
+
+async def test_button_command_and_label():
+    root, h = _build_form()
+    app = root._build_app()
+    async with app.run_test(size=(80, 24)) as pilot:
+        await pilot.pause()
+        await pilot.click(f"#{h['btn']._cid}")
+        await pilot.pause(0.3)
+        await pilot.click(f"#{h['btn']._cid}")
+        await pilot.pause(0.3)
+        assert h["state"]["clicks"] == 2
+        assert "clicked 2" in str(h["lab"]._widget.render())
+
+
+async def test_stringvar_pushes_to_entry():
+    root, h = _build_form()
+    app = root._build_app()
+    async with app.run_test(size=(80, 24)) as pilot:
+        await pilot.pause()
+        h["sv"].set("pushed")
+        await pilot.pause()
+        assert h["ent"]._widget.value == "pushed"
+
+
+async def test_entry_updates_stringvar_and_trace():
+    root, h = _build_form()
+    app = root._build_app()
+    async with app.run_test(size=(80, 24)) as pilot:
+        await pilot.pause()
+        h["ent"]._widget.focus()
+        await pilot.pause()
+        h["ent"]._widget.value = ""
+        await pilot.press("a", "b", "c")
+        await pilot.pause()
+        assert h["sv"].get() == "abc"
+        assert "abc" in h["state"]["traced"]
+
+
+async def test_checkbutton_with_booleanvar():
+    root, h = _build_form()
+    app = root._build_app()
+    async with app.run_test(size=(80, 24)) as pilot:
+        await pilot.pause()
+        await pilot.click(f"#{h['chk']._cid}")
+        await pilot.pause(0.3)
+        assert h["bv"].get() is True
+        assert h["state"]["checked"] is True
+
+
+async def test_progressbar_set():
+    root, h = _build_form()
+    app = root._build_app()
+    async with app.run_test(size=(80, 24)) as pilot:
+        await pilot.pause()
+        h["pb"].set(42)
+        await pilot.pause()
+        assert abs(h["pb"]._widget.progress - 42) < 0.01
+
+
+async def test_grid_layout_mounts_all():
+    root = tk.Tk()
+    grid = tk.Frame(root)
+    grid.pack(fill="both", expand=True)
+    for i, t in enumerate("789456123"):
+        tk.Button(grid, text=t).grid(row=i // 3, column=i % 3)
+    tk.Button(grid, text="0").grid(row=3, column=0, columnspan=3)
+
+    app = root._build_app()
+    async with app.run_test(size=(60, 20)) as pilot:
+        await pilot.pause()
+        from textual.widgets import Button as TButton
+        assert len(app.query(TButton)) == 10
+        # grid-size 应被算成 3 列 4 行
+        assert "grid-size: 3 4" in app.CSS
+
+
+def test_package_metadata():
+    assert tk.__version__ == "0.1.0"
+    for name in ("Tk", "Frame", "Label", "Button", "Entry", "StringVar"):
+        assert name in tk.__all__
+        assert hasattr(tk, name)