nextpytk 0.3.0__tar.gz → 0.4.0__tar.gz

nextpytk-0.3.0/README.md → nextpytk-0.4.0/PKG-INFO

@@ -1,9 +1,35 @@
-# nextpytk — Flask-style Decorator API for Tkinter
-
-nextpytk wraps Tkinter in Python decorators, inspired by Flask.
-Widget registration and layout are decoupled via dependency injection.
-All widgets expose a JSON schema for AI/LLM consumption.
-Uses ttk widgets where available (Button, Entry, Checkbutton, Radiobutton, Scale, Spinbox, Notebook).
+Metadata-Version: 2.4
+Name: nextpytk
+Version: 0.4.0
+Summary: Accessible, declarative Tkinter applications from ordinary Python functions.
+Project-URL: Homepage, https://github.com/nishimotz/nextpytk
+Project-URL: Repository, https://github.com/nishimotz/nextpytk
+Project-URL: Issues, https://github.com/nishimotz/nextpytk/issues
+Project-URL: Changelog, https://github.com/nishimotz/nextpytk/blob/main/ROADMAP.md
+Author: Takuya Nishimoto
+License: MIT
+License-File: LICENSE
+Keywords: accessibility,declarative-ui,gui,tkinter,ttk
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# nextpytk
+
+Accessible, declarative Tkinter applications from ordinary Python functions.
+
+Register widgets as plain Python functions, declare layout separately, and
+keep roles/descriptions in one place. The decorator style is Flask-inspired;
+`schema()` exports the same structure for agents and tools.
+Uses ttk widgets where available.
 
 ---
 
@@ -173,19 +199,25 @@ app.run(layout=b.build())
 | Decorator | Widget | Callback receives | Returns |
 |-----------|--------|-------------------|---------|
 | `@app.label(name, font=..., anchor=..., justify=..., padding=...)` | tk.Label | — | `str` or `dict` |
-| `@app.status(name)` | tk.Label (role=status) | — | `str` or `dict` |
+| `@app.status(name)` | tk.Label (`role=status` metadata) | — | `str` or `dict` |
 | `@app.message(name, width=..., auto_width=...)` | tk.Label (auto-wrap) | — | `str` or `dict` |
 | `@app.button(name, label=..., enabled_if=...)` | ttk.Button | entry values `dict` | `dict` |
 | `@app.job(name)` | async callable | entry values `dict` | `dict` |
 | `@app.entry(name, placeholder=..., show=...)` | ttk.Entry | `str` | `dict` |
 | `@app.checkbutton(name, text=...)` | ttk.Checkbutton | `bool` | `dict` |
 | `@app.radiobutton(name, text=..., value=..., group=...)` | ttk.Radiobutton | selected value `str` | `dict` |
+| `@app.combobox(name, values=..., readonly=...)` | ttk.Combobox | selected value `str` | `dict` |
+| `@app.menubar(name)` | tk.Menu (window menubar) | — | menu item list |
 | `@app.text(name, width=..., height=...)` | tk.Text | full content `str` | `dict` |
 | `@app.scale(name, from_=..., to=..., orient=...)` | ttk.Scale | value `str` | `dict` |
 | `@app.spinbox(name, from_=..., to=..., values=...)` | ttk.Spinbox | value `str` | `dict` |
 | `@app.listbox(name, items=..., selectmode=...)` | tk.Listbox | selected item `str` | `dict` |
 | `@app.canvas(name, width=..., height=...)` | tk.Canvas | — | — |
 
+`@app.status` sets schema / accessible `role="status"` metadata. It is **not** an ARIA live region yet (planned for a later release). Prefer it for operation feedback labels; use `@app.label` for static or high-frequency mirror text.
+
+`app.run(stages=..., tabposition=...)` and `@app.stages` provide state-driven screen switching (one visible stage at a time). Theme helpers (`apply_theme`, `tokens`, layout chrome) ship in the package root — see `examples/header_demo.py`.
+
 Label options:
 - `font`: e.g. `font=("TkDefaultFont", 18, "bold")`
 - `anchor`: e.g. `anchor="e"` (right-aligned)
@@ -234,6 +266,20 @@ Output is JSON-compatible and can serve as LLM Function Calling definitions.
 
 ---
 
+## Layout debug
+
+After widgets are built, `app.debug_layout()` returns JSON-compatible geometry
+and pack/grid info for every registered widget (useful for clipping, minsize,
+and layout regressions; also handy to hand to an agent).
+
+```python
+app.run(layout=["msg", "go"])  # or build via tests / custom runner
+print(app.debug_layout())
+# → {"title": "...", "sections": [{"widgets": [{"name": "msg", "geometry": ..., ...}, ...]}]}
+```
+
+---
+
 ## Async-Native (asyncio + Tkinter)
 
 `app.run_async()` runs the app on an asyncio event loop, cooperatively scheduled
@@ -257,7 +303,9 @@ uv run python examples/grid_temp.py          # temperature converter
 uv run python examples/task_panel.py          # multi-button panel
 uv run python examples/multiscreen.py         # order app with screens
 uv run python examples/widget_gallery.py      # all widget types
-uv run python examples/disk_usage_flat_viewer.py      # ncdu-style viewer (sync)
+uv run python examples/header_demo.py         # Layout.header / .status chrome
+uv run python examples/combobox_demo.py       # ttk.Combobox
+uv run python examples/menubar_demo.py        # menubar
 uv run python examples/disk_usage_flat_async.py       # ncdu-style viewer (async)
 ```
 
@@ -265,7 +313,7 @@ uv run python examples/disk_usage_flat_async.py       # ncdu-style viewer (async
 
 ## Requirements
 
-- Python 3.14 by default (`PYTHON=...` override supported)
+- Python 3.13+ (`requires-python`; examples default to 3.14 via `Makefile` `PYTHON=...`)
 - Tkinter support in your Python build
 - No other dependencies
 

nextpytk-0.3.0/PKG-INFO → nextpytk-0.4.0/README.md

@@ -1,20 +1,11 @@
-Metadata-Version: 2.4
-Name: nextpytk
-Version: 0.3.0
-Summary: Flask-style decorator API for tkinter GUI: schema-driven, A11y-first, agent-compatible.
-Project-URL: Homepage, https://github.com/nishimotz/nextpytk
-Author: Takuya Nishimoto
-License: MIT
-License-File: LICENSE
-Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-
-# nextpytk — Flask-style Decorator API for Tkinter
-
-nextpytk wraps Tkinter in Python decorators, inspired by Flask.
-Widget registration and layout are decoupled via dependency injection.
-All widgets expose a JSON schema for AI/LLM consumption.
-Uses ttk widgets where available (Button, Entry, Checkbutton, Radiobutton, Scale, Spinbox, Notebook).
+# nextpytk
+
+Accessible, declarative Tkinter applications from ordinary Python functions.
+
+Register widgets as plain Python functions, declare layout separately, and
+keep roles/descriptions in one place. The decorator style is Flask-inspired;
+`schema()` exports the same structure for agents and tools.
+Uses ttk widgets where available.
 
 ---
 
@@ -184,19 +175,25 @@ app.run(layout=b.build())
 | Decorator | Widget | Callback receives | Returns |
 |-----------|--------|-------------------|---------|
 | `@app.label(name, font=..., anchor=..., justify=..., padding=...)` | tk.Label | — | `str` or `dict` |
-| `@app.status(name)` | tk.Label (role=status) | — | `str` or `dict` |
+| `@app.status(name)` | tk.Label (`role=status` metadata) | — | `str` or `dict` |
 | `@app.message(name, width=..., auto_width=...)` | tk.Label (auto-wrap) | — | `str` or `dict` |
 | `@app.button(name, label=..., enabled_if=...)` | ttk.Button | entry values `dict` | `dict` |
 | `@app.job(name)` | async callable | entry values `dict` | `dict` |
 | `@app.entry(name, placeholder=..., show=...)` | ttk.Entry | `str` | `dict` |
 | `@app.checkbutton(name, text=...)` | ttk.Checkbutton | `bool` | `dict` |
 | `@app.radiobutton(name, text=..., value=..., group=...)` | ttk.Radiobutton | selected value `str` | `dict` |
+| `@app.combobox(name, values=..., readonly=...)` | ttk.Combobox | selected value `str` | `dict` |
+| `@app.menubar(name)` | tk.Menu (window menubar) | — | menu item list |
 | `@app.text(name, width=..., height=...)` | tk.Text | full content `str` | `dict` |
 | `@app.scale(name, from_=..., to=..., orient=...)` | ttk.Scale | value `str` | `dict` |
 | `@app.spinbox(name, from_=..., to=..., values=...)` | ttk.Spinbox | value `str` | `dict` |
 | `@app.listbox(name, items=..., selectmode=...)` | tk.Listbox | selected item `str` | `dict` |
 | `@app.canvas(name, width=..., height=...)` | tk.Canvas | — | — |
 
+`@app.status` sets schema / accessible `role="status"` metadata. It is **not** an ARIA live region yet (planned for a later release). Prefer it for operation feedback labels; use `@app.label` for static or high-frequency mirror text.
+
+`app.run(stages=..., tabposition=...)` and `@app.stages` provide state-driven screen switching (one visible stage at a time). Theme helpers (`apply_theme`, `tokens`, layout chrome) ship in the package root — see `examples/header_demo.py`.
+
 Label options:
 - `font`: e.g. `font=("TkDefaultFont", 18, "bold")`
 - `anchor`: e.g. `anchor="e"` (right-aligned)
@@ -245,6 +242,20 @@ Output is JSON-compatible and can serve as LLM Function Calling definitions.
 
 ---
 
+## Layout debug
+
+After widgets are built, `app.debug_layout()` returns JSON-compatible geometry
+and pack/grid info for every registered widget (useful for clipping, minsize,
+and layout regressions; also handy to hand to an agent).
+
+```python
+app.run(layout=["msg", "go"])  # or build via tests / custom runner
+print(app.debug_layout())
+# → {"title": "...", "sections": [{"widgets": [{"name": "msg", "geometry": ..., ...}, ...]}]}
+```
+
+---
+
 ## Async-Native (asyncio + Tkinter)
 
 `app.run_async()` runs the app on an asyncio event loop, cooperatively scheduled
@@ -268,7 +279,9 @@ uv run python examples/grid_temp.py          # temperature converter
 uv run python examples/task_panel.py          # multi-button panel
 uv run python examples/multiscreen.py         # order app with screens
 uv run python examples/widget_gallery.py      # all widget types
-uv run python examples/disk_usage_flat_viewer.py      # ncdu-style viewer (sync)
+uv run python examples/header_demo.py         # Layout.header / .status chrome
+uv run python examples/combobox_demo.py       # ttk.Combobox
+uv run python examples/menubar_demo.py        # menubar
 uv run python examples/disk_usage_flat_async.py       # ncdu-style viewer (async)
 ```
 
@@ -276,7 +289,7 @@ uv run python examples/disk_usage_flat_async.py       # ncdu-style viewer (async
 
 ## Requirements
 
-- Python 3.14 by default (`PYTHON=...` override supported)
+- Python 3.13+ (`requires-python`; examples default to 3.14 via `Makefile` `PYTHON=...`)
 - Tkinter support in your Python build
 - No other dependencies
 

{nextpytk-0.3.0 → nextpytk-0.4.0}/ROADMAP.md

@@ -1,57 +1,58 @@
 # ROADMAP — nextpytk
 
-## Snapshot (v0.3.0)
+## Snapshot (v0.4.0)
 
 ### Implemented widgets (`@app.*`)
 
 | kind | Notes |
 |------|-------|
-| `label` / `status` / `message` | Display / word-wrap |
+| `label` / `status` / `message` | Display / word-wrap. `status` sets `role=status` metadata (not a live region yet) |
 | `button` / `entry` | ttk, `state=` support |
 | `checkbutton` / `radiobutton` / `scale` / `spinbox` | ttk |
-| `text` / `listbox` / `canvas` | tk (Text: tags, paired sync pending) |
+| `combobox` | ttk.Combobox (`readonly`, `values`) |
+| `menubar` | Window menubar with cascades / `enabled_if` |
+| `text` / `listbox` / `canvas` | tk (Text: tags, readonly, paired y-scroll sync) |
 | `treeview` | Multi-column (`show="headings"`) |
 | `paned` | `ttk.Panedwindow` + `with app.pane(...)` |
 | `progressbar` | `state[key]` / `{name}_running` for determinate/indeterminate |
 | `bind` | Global shortcuts (annotates matching button) |
 
-Infrastructure: `Layout` (pack/grid), `@app.multiview`, `run` / `run_async` / `spawn` / `@app.job`, `schema()`, builder registry, a11y choke point `_apply_a11y`.
+Infrastructure: `Layout` (pack/grid, `.header()` / `.status()` chrome), `@app.multiview`, `@app.stages` / `run(stages=..., tabposition=...)`, `run` / `run_async` / `spawn` / `@app.job`, `schema()`, `debug_layout()`, builder registry, a11y choke point `_apply_a11y`.
 
----
+Theme: `tokens` + `apply_theme` / layout helpers (contrast + 44px target-size regressions).
 
-## Near term (v0.3.x)
+PyPI: Trusted Publishing on `v*` tag push (`.github/workflows/publish.yml`).
 
-### Type hints
+### Examples
 
-- [ ] TypedDict / Protocol for decorator arguments (Pyright/mypy completion)
-- [ ] Literal types for tkinter constants (`tk.LEFT`, `tk.RIGHT`, `tk.NSEW`, etc.)
-- [ ] Fluent API equivalent to `_GridBuilder.columnconfigure`
+- `disk_usage_flat_async.py` — async ncdu-style viewer (`run_async` + `spawn`)
+- `combobox_demo.py`, `menubar_demo.py`, `header_demo.py`, `text_sync_demo.py`
 
-### Widget expansion
+---
 
-- [ ] `@app.combobox` / `@app.menubar`
-- [ ] Per-widget `bind` (`<<ListboxSelect>>`, `<Double-1>`, etc. — separate from global `bind`)
-- [ ] listbox callback value design: pass selection index instead of display string (unify with `treeview`)
-- [ ] `@app.text` enhancements — `tag_config`, read-only, paired sync scroll
+## Near term (post-0.4)
 
 ### A11y
 
+- [ ] `@app.status` live-region behavior (ARIA `aria-live` equivalent / WCAG 4.1.3)
 - [ ] Tk 9.1 `tk accessible set_acc_*` real-device verification (9.1b0 + NVDA)
 - [ ] Role vocabulary mapping to Tk side
 - [ ] Automatic `emit_selection_change` (leverage `apply_state` knowing which widgets changed)
 
+### Type hints
+
+- [ ] Further TypedDict / Protocol coverage for decorator arguments
+- [ ] Fluent API equivalent to `_GridBuilder.columnconfigure`
+
+### Widget expansion
+
+- [ ] Per-widget `bind` (`<<ListboxSelect>>`, `<Double-1>`, etc. — separate from global `bind`)
+- [ ] listbox callback value design: pass selection index instead of display string (unify with `treeview`)
+
 ### Layout DSL
 
 - [ ] Nested frames (`Layout` inside `Layout`)
 - [ ] Global default for `padx`/`pady`
-- [ ] `Layout.paired(..., sync_yscroll=True)` — left/right text sync
-
-### Public runtime API
-
-- [x] `build_widgets()`, `widget()`, `widget_kind()`, `widget_specs()`
-- [x] `apply_state()`, `sync()` — reusable from custom runners
-- [x] `app.run(multiview="...")` entry point
-- [x] `register_widget_builder()` — public API for custom kinds
 
 ### Agent / LLM integration
 
@@ -68,14 +69,6 @@ Infrastructure: `Layout` (pack/grid), `@app.multiview`, `run` / `run_async` / `s
 - [ ] `Layout.style("my_button", background=..., font=...)` style definitions
 - [ ] Theme switching (`ttk.Style().theme_use(...)`)
 
-### Async job integration
-
-- [x] `app.run_async()` + `app.spawn()` — async event loop coexisting with Tk
-- [x] `app.spawn(asyncio.to_thread(...))` for non-blocking background jobs
-- [x] Sync example: `disk_usage_flat_viewer.py`
-- [x] Async example: `disk_usage_flat_async.py` (`app.run_async()` + `app.spawn()`)
-- [x] `@app.job(name)` — register async callbacks as @app decorators
-
 ### Declarative components
 
 - [ ] `@app.component` decorator (React-like reuse, replacing `Layout`)
@@ -85,3 +78,12 @@ Infrastructure: `Layout` (pack/grid), `@app.multiview`, `run` / `run_async` / `s
 
 - [x] Headless execution tests (`tests/` — withdrawn root, build/apply_state/callback drive)
 - [ ] WidgetSpec unit tests
+
+---
+
+## Earlier snapshots
+
+### v0.3.0
+
+Builder registry, headless tests, a11y wiring (`_apply_a11y`), error policy, bugfixes.
+`run_async` / `spawn` / `@app.job`, public runtime API (`build_widgets`, `apply_state`, `register_widget_builder`, …).

nextpytk-0.4.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling>=1.18.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nextpytk"
+version = "0.4.0"
+description = "Accessible, declarative Tkinter applications from ordinary Python functions."
+readme = "README.md"
+requires-python = ">=3.13"
+license = { text = "MIT" }
+authors = [{ name = "Takuya Nishimoto" }]
+keywords = ["tkinter", "ttk", "gui", "accessibility", "declarative-ui"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: User Interfaces",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/nishimotz/nextpytk"
+Repository = "https://github.com/nishimotz/nextpytk"
+Issues = "https://github.com/nishimotz/nextpytk/issues"
+Changelog = "https://github.com/nishimotz/nextpytk/blob/main/ROADMAP.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nextpytk"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/nextpytk", "README.md", "ROADMAP.md"]
+
+[tool.uv]
+package = true
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.409",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nextpytk-0.4.0/src/nextpytk/__init__.py

@@ -0,0 +1,42 @@
+"""nextpytk: accessible, declarative Tkinter apps from ordinary Python functions."""
+
+from nextpytk.app import TkApp
+from nextpytk.layout import Layout, LayoutBuilder
+from nextpytk import types
+from nextpytk.widgets import WidgetSpec
+from nextpytk.theme import (
+    apply_theme,
+    configure_window,
+    content_frame,
+    divider,
+    heading,
+    field_row,
+    window_header,
+    data_list,
+    add_row,
+    clear_rows,
+    status_bar,
+    button,
+)
+from nextpytk import tokens
+
+__all__ = [
+    "TkApp",
+    "Layout",
+    "LayoutBuilder",
+    "WidgetSpec",
+    "types",
+    "apply_theme",
+    "configure_window",
+    "content_frame",
+    "divider",
+    "heading",
+    "field_row",
+    "window_header",
+    "data_list",
+    "add_row",
+    "clear_rows",
+    "status_bar",
+    "button",
+    "tokens",
+]