taut.tk 0.1.0__tar.gz

taut_tk-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.3
+Name: taut.tk
+Version: 0.1.0
+Summary: Add your description here
+Author: Sam I
+Author-email: Sam I <aweptimum@gmail.com>
+Requires-Dist: reaktiv>=0.22.0
+Requires-Dist: pillow>=12.2.0 ; extra == 'dev'
+Requires-Dist: watchdog>=6.0.0 ; extra == 'dev'
+Requires-Python: >=3.13
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# taut.tk
+
+A small SolidJS-inspired runtime for Tkinter using
+[reaktiv](https://pypi.org/project/reaktiv/) for fine-grained signals.
+
+This is currently a prototype that I hope makes Tkinter more fun
+
+```python
+from typing import Protocol
+
+from taut import component
+from taut import layout
+from taut import tk
+from taut.reactive import Accessor
+from taut.reactive import Mutator
+from taut.reactive import create_signal
+from taut.runtime import create_root
+from taut.control import For
+from taut.control import Show
+
+
+class CounterProps(Protocol):
+    label: Accessor[str]
+    count: Accessor[int]
+    set_count: Mutator[int]
+
+
+@component
+def counter(props: CounterProps):
+    todos, set_todos = create_signal(["wire props", "own effects", "dispose cleanly"])
+
+    return layout.VStack(
+        tk.Label(text=lambda: f"{props.label()}: {props.count()}"),
+        tk.Button(text="Increment", on_click=lambda: props.set_count(lambda n: n + 1)),
+        Show(
+            lambda: props.count() % 2 == 0,
+            lambda: tk.Label(text="Even"),
+            fallback=lambda: tk.Label(text="Odd"),
+        ),
+        For(todos, lambda item: tk.Label(text=item), key=lambda item: item),
+        layout.HStack(
+            tk.Button(text="-", on_click=lambda: set_todos(lambda items: items[:-1])),
+            gap=6,
+        ),
+        padding=12,
+        gap=6,
+    )
+
+count, set_count = create_signal(0)
+mount = create_root(
+    lambda: counter(label="Solid TK", count=count, set_count=set_count),
+    title="Solid TK",
+)
+mount.widget.mainloop()
+```
+
+## Why Tk?
+I keep reaching for it every time I want a small UI at work and I keep getting bogged down in abstractions I think are loose but turn out to be more tightly-coupled than I realize. Imperatively updating state is also a chore and makes for widgets with lots of clunky helpers, and I find widget vars unwieldy. My most recent attempt I threw `reaktiv` at the problem and was surprised at how streamlined it made my widgets. I felt it could be more. So here we are.
+
+## What's Here So Far
+
+- Functional components using `@component` decorator
+- Class `Component` with `__init__()/setup()` and `render()`
+- `Props`, where every attribute is an accessor
+- first-class component children through `props.children`
+- transparent `Fragment(...)` nodes for returning multiple children
+- widget namespaces: `tk` for classic Tk widgets and `ttk` for themed widgets
+- layout namespace: `layout.VStack`, `layout.HStack`, `layout.Grid`, `layout.Item`, `layout.GridItem`
+- StyleX-ish style objects agnostic to tk/ttk widgets with `style.define()`, `style.merge()`, and `style.component()`.
+- some control flow: `Show`, `For`, `Switch` / `Match`, `Index`, `Dynamic`
+- context: `create_context()`, `Provider`, `use_context()`
+- stores: `create_store()` for immutable updates and `create_mutable()` for
+  Solid-style mutable object state
+- resources: `create_resource()` with `loading`, `error`, `state`, `mutate`, `refetch`
+- lifecycle helpers: `create_effect()`, `on_mount()`, `on_cleanup()`
+- `create_root()` and explicit disposal through the returned `Mount`
+
+## Doc Topics
+
+- [Context](docs/context.md): providers, typed context helpers, and forwarded children.
+- [Control](docs/control.md): conditional rendering.
+- [Reactive primitives](docs/reactive.md): signals, memos, effects, and owner cleanup.
+- [Resources](docs/resources.md): worker-thread loading, refreshes, mutation, and status.
+- [Scheduling](docs/scheduling.md): queueing work
+- [Stores](docs/stores.md): state management
+- [Style](docs/style.md): StyleX-ish style objects, merging, and component styling.
+- [Widgets](docs/widgets.md): Tkinter primitives
+
+## Examples
+
+The runnable examples live in [examples](../examples/). Start with the
+[examples README](../examples/README.md) for a short path through them.
+
+## Strong Typing
+To follow Solid's model of named args collected into reactive props, there is some brittle trickery.
+
+In JS/TS land, there's tons of tooling around jsx/tsx. Python doesn't have that.<br>What it *does* have are .pyi files. We can define parameter transformations that type checkers can't inspect and then give them the publc facing API with a wink and a smile. The problem is generating those .pyi files.
+
+The beginning of solving that problem is the `@component` decorator. In addition to transforming functions into rendered nodes, is also a syntax marker that can be inspected. 
+
+The next bit is stub-genning; basically a build step. Files in the working directory are scanned for component declarations and a corresponding `.pyi` file is generated, unrolling the typed prop object into a function signature.
+
+This process can be manual with `uv run taut.tk stubs .`, or you can run a watcher to do it live with `uv run taut.tk watch` (it might be brittle though).
+
+There are some caveats though, as this bit is honestly harder and more involved than the actual framework to get right. It imposes some limitations on import patterns.
+
+When a component module imports sibling modules, prefer `from . import <module>` or a direct submodule import like `import examples.todo.module`. Relying on imports that use `__init__.py`, like `from examples.todo import module`, can route through generated package stubs instead of the source module. This is a limitation imposed by the current state of type checkers, and the only real work around that preserves usage of `__init__.py` is stubbing *everything*. Not really a feasible thing to develop or maintain right now.
+
+## Design Notes
+
+`create_signal()` returns an accessor and a mutator:
+
+```python
+from taut.reactive import create_signal
+count, set_count = create_signal(0)
+count()
+set_count(lambda value: value + 1)
+```
+
+The accessor is still compatible with `reaktiv` signals, so widgets can bind to
+it directly. Writable widgets such as `tk.Entry(value=..., on_input=...)` receive
+the accessor and mutator separately.
+
+`Component.__new__` returns a renderable node to keep the class API simple
+
+```python
+Counter(title="Solid TK")
+```
+
+Inside a component, `self.props.title()` reads a reaktiv signal. This is
+intentionally accessor-oriented.
+
+Existing signals are preserved, while plain values and callbacks are wrapped as
+signal values. Tk widget props use one additional convention: callable non-event
+props are treated as reactive bindings, and event props such as `on_click` /
+`command` are passed through as callbacks.
+
+```python
+tk.Label(text=f"{count()}")                  # snapshot now
+tk.Label(text=count)                         # reactive signal value
+tk.Label(text=lambda: f"{count()}")          # reactive derived expression
+```
+
+That means a component prop can be read inside a derived expression:
+
+```python
+tk.Label(text=lambda: f"Hello {self.props.name()}")
+```
+
+or forwarded directly to a widget prop:
+
+```python
+tk.Label(text=self.props.name)
+```
+
+Component children are also collected into `props.children`, so container-like
+components can feel like Solid components instead of manually passing a
+`children=` prop:
+
+```python
+@component
+def panel(props):
+    return layout.VStack(
+        tk.Label(text=props.title),
+        props.children(),
+        padding=8,
+    )
+
+panel(tk.Label(text="Nested"), title="Details")
+```
+
+Control-flow nodes and `Fragment(...)` are transparent to layout. They produce
+children; the parent widget or layout helper decides where those children go:
+
+```python
+@component
+def rows(props):
+    return For(props.items, lambda item: tk.Label(text=item), key=lambda item: item)
+
+layout.VStack(
+    tk.Label(text="Before"),
+    rows(items=todos),
+    tk.Label(text="After"),
+)
+```
+
+In that example, the repeated labels are laid out by `VStack` between
+`Before` and `After`; `For` and the component do not create wrapper frames.
+
+## Benchmarks
+
+To estimate framework overhead without needing a display server, run the fake-Tk
+benchmark:
+
+```sh
+uv run python benchmarks/bench_overhead.py
+```
+
+It compares raw Tk-style widget creation with taut.tk mounting for static
+labels, reactive label props, and a component wrapper. The most useful line is
+the reported extra microseconds per widget, because native Tk/Tcl startup and
+platform display behavior are intentionally excluded.

taut_tk-0.1.0/README.md

@@ -0,0 +1,202 @@
+# taut.tk
+
+A small SolidJS-inspired runtime for Tkinter using
+[reaktiv](https://pypi.org/project/reaktiv/) for fine-grained signals.
+
+This is currently a prototype that I hope makes Tkinter more fun
+
+```python
+from typing import Protocol
+
+from taut import component
+from taut import layout
+from taut import tk
+from taut.reactive import Accessor
+from taut.reactive import Mutator
+from taut.reactive import create_signal
+from taut.runtime import create_root
+from taut.control import For
+from taut.control import Show
+
+
+class CounterProps(Protocol):
+    label: Accessor[str]
+    count: Accessor[int]
+    set_count: Mutator[int]
+
+
+@component
+def counter(props: CounterProps):
+    todos, set_todos = create_signal(["wire props", "own effects", "dispose cleanly"])
+
+    return layout.VStack(
+        tk.Label(text=lambda: f"{props.label()}: {props.count()}"),
+        tk.Button(text="Increment", on_click=lambda: props.set_count(lambda n: n + 1)),
+        Show(
+            lambda: props.count() % 2 == 0,
+            lambda: tk.Label(text="Even"),
+            fallback=lambda: tk.Label(text="Odd"),
+        ),
+        For(todos, lambda item: tk.Label(text=item), key=lambda item: item),
+        layout.HStack(
+            tk.Button(text="-", on_click=lambda: set_todos(lambda items: items[:-1])),
+            gap=6,
+        ),
+        padding=12,
+        gap=6,
+    )
+
+count, set_count = create_signal(0)
+mount = create_root(
+    lambda: counter(label="Solid TK", count=count, set_count=set_count),
+    title="Solid TK",
+)
+mount.widget.mainloop()
+```
+
+## Why Tk?
+I keep reaching for it every time I want a small UI at work and I keep getting bogged down in abstractions I think are loose but turn out to be more tightly-coupled than I realize. Imperatively updating state is also a chore and makes for widgets with lots of clunky helpers, and I find widget vars unwieldy. My most recent attempt I threw `reaktiv` at the problem and was surprised at how streamlined it made my widgets. I felt it could be more. So here we are.
+
+## What's Here So Far
+
+- Functional components using `@component` decorator
+- Class `Component` with `__init__()/setup()` and `render()`
+- `Props`, where every attribute is an accessor
+- first-class component children through `props.children`
+- transparent `Fragment(...)` nodes for returning multiple children
+- widget namespaces: `tk` for classic Tk widgets and `ttk` for themed widgets
+- layout namespace: `layout.VStack`, `layout.HStack`, `layout.Grid`, `layout.Item`, `layout.GridItem`
+- StyleX-ish style objects agnostic to tk/ttk widgets with `style.define()`, `style.merge()`, and `style.component()`.
+- some control flow: `Show`, `For`, `Switch` / `Match`, `Index`, `Dynamic`
+- context: `create_context()`, `Provider`, `use_context()`
+- stores: `create_store()` for immutable updates and `create_mutable()` for
+  Solid-style mutable object state
+- resources: `create_resource()` with `loading`, `error`, `state`, `mutate`, `refetch`
+- lifecycle helpers: `create_effect()`, `on_mount()`, `on_cleanup()`
+- `create_root()` and explicit disposal through the returned `Mount`
+
+## Doc Topics
+
+- [Context](docs/context.md): providers, typed context helpers, and forwarded children.
+- [Control](docs/control.md): conditional rendering.
+- [Reactive primitives](docs/reactive.md): signals, memos, effects, and owner cleanup.
+- [Resources](docs/resources.md): worker-thread loading, refreshes, mutation, and status.
+- [Scheduling](docs/scheduling.md): queueing work
+- [Stores](docs/stores.md): state management
+- [Style](docs/style.md): StyleX-ish style objects, merging, and component styling.
+- [Widgets](docs/widgets.md): Tkinter primitives
+
+## Examples
+
+The runnable examples live in [examples](../examples/). Start with the
+[examples README](../examples/README.md) for a short path through them.
+
+## Strong Typing
+To follow Solid's model of named args collected into reactive props, there is some brittle trickery.
+
+In JS/TS land, there's tons of tooling around jsx/tsx. Python doesn't have that.<br>What it *does* have are .pyi files. We can define parameter transformations that type checkers can't inspect and then give them the publc facing API with a wink and a smile. The problem is generating those .pyi files.
+
+The beginning of solving that problem is the `@component` decorator. In addition to transforming functions into rendered nodes, is also a syntax marker that can be inspected. 
+
+The next bit is stub-genning; basically a build step. Files in the working directory are scanned for component declarations and a corresponding `.pyi` file is generated, unrolling the typed prop object into a function signature.
+
+This process can be manual with `uv run taut.tk stubs .`, or you can run a watcher to do it live with `uv run taut.tk watch` (it might be brittle though).
+
+There are some caveats though, as this bit is honestly harder and more involved than the actual framework to get right. It imposes some limitations on import patterns.
+
+When a component module imports sibling modules, prefer `from . import <module>` or a direct submodule import like `import examples.todo.module`. Relying on imports that use `__init__.py`, like `from examples.todo import module`, can route through generated package stubs instead of the source module. This is a limitation imposed by the current state of type checkers, and the only real work around that preserves usage of `__init__.py` is stubbing *everything*. Not really a feasible thing to develop or maintain right now.
+
+## Design Notes
+
+`create_signal()` returns an accessor and a mutator:
+
+```python
+from taut.reactive import create_signal
+count, set_count = create_signal(0)
+count()
+set_count(lambda value: value + 1)
+```
+
+The accessor is still compatible with `reaktiv` signals, so widgets can bind to
+it directly. Writable widgets such as `tk.Entry(value=..., on_input=...)` receive
+the accessor and mutator separately.
+
+`Component.__new__` returns a renderable node to keep the class API simple
+
+```python
+Counter(title="Solid TK")
+```
+
+Inside a component, `self.props.title()` reads a reaktiv signal. This is
+intentionally accessor-oriented.
+
+Existing signals are preserved, while plain values and callbacks are wrapped as
+signal values. Tk widget props use one additional convention: callable non-event
+props are treated as reactive bindings, and event props such as `on_click` /
+`command` are passed through as callbacks.
+
+```python
+tk.Label(text=f"{count()}")                  # snapshot now
+tk.Label(text=count)                         # reactive signal value
+tk.Label(text=lambda: f"{count()}")          # reactive derived expression
+```
+
+That means a component prop can be read inside a derived expression:
+
+```python
+tk.Label(text=lambda: f"Hello {self.props.name()}")
+```
+
+or forwarded directly to a widget prop:
+
+```python
+tk.Label(text=self.props.name)
+```
+
+Component children are also collected into `props.children`, so container-like
+components can feel like Solid components instead of manually passing a
+`children=` prop:
+
+```python
+@component
+def panel(props):
+    return layout.VStack(
+        tk.Label(text=props.title),
+        props.children(),
+        padding=8,
+    )
+
+panel(tk.Label(text="Nested"), title="Details")
+```
+
+Control-flow nodes and `Fragment(...)` are transparent to layout. They produce
+children; the parent widget or layout helper decides where those children go:
+
+```python
+@component
+def rows(props):
+    return For(props.items, lambda item: tk.Label(text=item), key=lambda item: item)
+
+layout.VStack(
+    tk.Label(text="Before"),
+    rows(items=todos),
+    tk.Label(text="After"),
+)
+```
+
+In that example, the repeated labels are laid out by `VStack` between
+`Before` and `After`; `For` and the component do not create wrapper frames.
+
+## Benchmarks
+
+To estimate framework overhead without needing a display server, run the fake-Tk
+benchmark:
+
+```sh
+uv run python benchmarks/bench_overhead.py
+```
+
+It compares raw Tk-style widget creation with taut.tk mounting for static
+labels, reactive label props, and a component wrapper. The most useful line is
+the reported extra microseconds per widget, because native Tk/Tcl startup and
+platform display behavior are intentionally excluded.

taut_tk-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "taut.tk"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Sam I", email = "aweptimum@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "reaktiv>=0.22.0",
+]
+
+[project.scripts]
+taut = "taut.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pillow>=12.2.0",
+    "watchdog>=6.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "taut"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.410",
+    "pytest>=9.1.1",
+    "ruff>=0.15.18",
+]

taut_tk-0.1.0/src/taut/__init__.py

@@ -0,0 +1,35 @@
+"""A Solid-style layer for Tkinter powered by reaktiv."""
+
+from . import context
+from . import control
+from . import layout
+from . import props
+from . import reactive
+from . import resource
+from . import runtime
+from . import stores
+from . import style
+from . import tk
+from . import tk_props
+from . import ttk
+from .component import Component
+from .component import component
+from .runtime import Fragment
+
+__all__ = [
+    "Component",
+    "Fragment",
+    "component",
+    "context",
+    "control",
+    "layout",
+    "props",
+    "reactive",
+    "resource",
+    "runtime",
+    "style",
+    "stores",
+    "tk",
+    "tk_props",
+    "ttk",
+]

taut_tk-0.1.0/src/taut/cli/__init__.py

@@ -0,0 +1,36 @@
+import argparse
+from pathlib import Path
+
+from taut.cli.stubs import main_cli as stubby
+from taut.cli.watch import main as watcher
+
+
+def main():
+    parser = argparse.ArgumentParser(description="taut.tk development tools.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    parser_stubs = subparsers.add_parser("stubs", help="Generate taut.tk .pyi stubs.")
+    parser_stubs.add_argument("paths", nargs="+", type=Path)
+    parser_stubs.add_argument(
+        "-o",
+        "--out-dir",
+        default="typings",
+        type=Path,
+        help="Directory for generated stubs. Defaults to typings.",
+    )
+    parser_stubs.add_argument(
+        "--in-place",
+        action="store_true",
+        help="Write sibling .pyi files next to source files.",
+    )
+    parser_stubs.set_defaults(func=stubby)
+
+    parser_watch = subparsers.add_parser("watch", help="Regenerate .pyi stubs on edits.")
+    parser_watch.set_defaults(func=watcher)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

taut_tk-0.1.0/src/taut/cli/stub_model.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+
+@dataclass
+class PropField:
+    name: str
+    internal_type: str
+    external_type: str
+
+
+@dataclass
+class ComponentStub:
+    name: str
+    fields: list[PropField]
+
+
+@dataclass
+class ImportStub:
+    module: str
+    name: str
+    export_name: str
+
+
+def collect_protocols(module: ast.Module) -> dict[str, list[PropField]]:
+    protocols: dict[str, list[PropField]] = {}
+    for node in module.body:
+        if not isinstance(node, ast.ClassDef):
+            continue
+        if not any(base_name(base) == "Protocol" for base in node.bases):
+            continue
+
+        protocols[node.name] = [
+            PropField(
+                statement.target.id,
+                ast.unparse(statement.annotation),
+                external_prop_type(ast.unparse(statement.annotation)),
+            )
+            for statement in node.body
+            if isinstance(statement, ast.AnnAssign)
+            and isinstance(statement.target, ast.Name)
+        ]
+    return protocols
+
+
+def collect_components(
+    module: ast.Module,
+    protocols: dict[str, list[PropField]],
+) -> list[ComponentStub]:
+    components: list[ComponentStub] = []
+    for node in module.body:
+        if isinstance(node, ast.FunctionDef) and is_component_function(node):
+            protocol_name = first_arg_annotation(node)
+        elif isinstance(node, ast.ClassDef) and is_component_class(node):
+            protocol_name = init_props_annotation(node)
+        else:
+            continue
+
+        if protocol_name is None:
+            components.append(ComponentStub(node.name, []))
+        elif protocol_name in protocols:
+            components.append(ComponentStub(node.name, protocols[protocol_name]))
+    return components
+
+
+def collect_public_imports(module: ast.Module) -> list[ImportStub]:
+    imports: list[ImportStub] = []
+    for node in module.body:
+        if not isinstance(node, ast.ImportFrom) or node.module is None:
+            continue
+        if node.module in {"__future__", "typing"} or node.module.startswith("solid_tk"):
+            continue
+        module_name = "." * node.level + node.module
+        for alias in node.names:
+            export_name = alias.asname or alias.name
+            if export_name.startswith("_"):
+                continue
+            imports.append(ImportStub(module_name, alias.name, export_name))
+    return imports
+
+
+def render_component(component: ComponentStub) -> list[str]:
+    fields = [field for field in component.fields if field.name != "children"]
+    children_field = next(
+        (field for field in component.fields if field.name == "children"),
+        None,
+    )
+
+    if not component.fields:
+        return [
+            f"def {component.name}("
+            "*child_nodes: Any, children: Any = ..."
+            ") -> runtime.Node: ..."
+        ]
+
+    lines = [f"def {component.name}(", "    *child_nodes: Any,"]
+    lines.extend(f"    {field.name}: {field.external_type}," for field in fields)
+    if children_field is not None:
+        lines.append(f"    children: {children_field.external_type},")
+    else:
+        lines.append("    children: Any = ...,")
+    lines.append(") -> runtime.Node: ...")
+    return lines
+
+
+def is_component_function(node: ast.FunctionDef) -> bool:
+    return any(base_name(decorator) == "component" for decorator in node.decorator_list)
+
+
+def is_component_class(node: ast.ClassDef) -> bool:
+    return any(base_name(base) == "Component" for base in node.bases)
+
+
+def first_arg_annotation(node: ast.FunctionDef) -> str | None:
+    if not node.args.args:
+        return None
+    annotation = node.args.args[0].annotation
+    return ast.unparse(annotation) if annotation is not None else None
+
+
+def init_props_annotation(node: ast.ClassDef) -> str | None:
+    for statement in node.body:
+        if not isinstance(statement, ast.FunctionDef) or statement.name != "__init__":
+            continue
+        if len(statement.args.args) < 2:
+            return None
+        annotation = statement.args.args[1].annotation
+        return ast.unparse(annotation) if annotation is not None else None
+    return None
+
+
+def external_prop_type(internal_type: str) -> str:
+    if internal_type.startswith("Accessor[") and internal_type.endswith("]"):
+        inner = internal_type.removeprefix("Accessor[").removesuffix("]")
+        return f"{inner} | reactive.Accessor[{inner}]"
+    if internal_type.startswith("reactive.Accessor[") and internal_type.endswith("]"):
+        inner = internal_type.removeprefix("reactive.Accessor[").removesuffix("]")
+        return f"{inner} | reactive.Accessor[{inner}]"
+    if internal_type.startswith("Mutator[") and internal_type.endswith("]"):
+        inner = internal_type.removeprefix("Mutator[").removesuffix("]")
+        return f"reactive.Mutator[{inner}]"
+    if internal_type.startswith("reactive.Mutator[") and internal_type.endswith("]"):
+        return internal_type
+    return "Any"
+
+
+def base_name(node: ast.AST) -> str:
+    match node:
+        case ast.Name(id=name):
+            return name
+        case ast.Attribute(attr=name):
+            return name
+        case ast.Call(func=func):
+            return base_name(func)
+        case ast.Subscript(value=value):
+            return base_name(value)
+        case _:
+            return ""
+