taut.tk 0.1.0__py3-none-any.whl

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/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/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 ""
+

taut/cli/stubs.py

@@ -0,0 +1,393 @@
+from __future__ import annotations
+
+import ast
+import shutil
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+from .stub_model import ComponentStub
+from .stub_model import ImportStub
+from .stub_model import collect_components
+from .stub_model import collect_protocols
+from .stub_model import collect_public_imports
+from .stub_model import render_component
+
+DEFAULT_OUT_DIR = Path("typings")
+SKIPPED_DIRS = {
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "typings",
+}
+
+
+@dataclass
+class GeneratedModule:
+    output_path: Path
+    import_path: str
+    components: list[ComponentStub]
+    public_imports: list[ImportStub]
+
+
+def main_cli(args):
+    main(args.paths, args.out_dir, args.in_place)
+
+
+def main(paths: list[Path], out_dir: Path = DEFAULT_OUT_DIR, in_place=False) -> None:
+    all_source_paths = list(expand_paths(paths))
+    modules = [
+        module
+        for path in all_source_paths
+        if (module := generate_module(path, out_dir, in_place=in_place)) is not None
+    ]
+    generated_import_paths = {module.import_path for module in modules}
+
+    for module in modules:
+        module.output_path.parent.mkdir(parents=True, exist_ok=True)
+        module.output_path.write_text(
+            render_stub(
+                module.components,
+                module.public_imports,
+                generated_import_paths=generated_import_paths,
+            ),
+            encoding="utf-8",
+        )
+
+    if not in_place:
+        write_package_exports(modules, all_source_paths, out_dir)
+
+
+def expand_paths(paths: Iterable[Path]) -> Iterable[Path]:
+    for path in paths:
+        if path.is_dir():
+            yield from sorted(
+                child for child in path.rglob("*.py") if not is_skipped_path(child)
+            )
+        elif path.suffix == ".py":
+            yield path
+
+
+def is_skipped_path(path: Path) -> bool:
+    return any(part in SKIPPED_DIRS for part in path.parts)
+
+
+def output_path_for(path: Path, out_dir: Path, in_place: bool) -> Path:
+    if in_place:
+        return path.with_suffix(".pyi")
+
+    rel = path.resolve().relative_to(Path.cwd())
+    return out_dir / rel.with_suffix(".pyi")
+
+
+def read_module(path: Path) -> ast.Module | None:
+    try:
+        return ast.parse(path.read_text(encoding="utf-8"))
+    except (OSError, SyntaxError):
+        return None
+
+
+def remove_stub_for_source(
+    path: Path,
+    out_dir: Path = DEFAULT_OUT_DIR,
+    in_place: bool = False,
+) -> bool:
+    try:
+        output_path = output_path_for(path, out_dir, in_place)
+    except ValueError:
+        return False
+    try:
+        output_path.unlink()
+    except FileNotFoundError:
+        return False
+    return True
+
+
+def remove_stubs_for_source_dir(
+    path: Path,
+    out_dir: Path = DEFAULT_OUT_DIR,
+) -> bool:
+    try:
+        rel = path.resolve().relative_to(Path.cwd())
+    except ValueError:
+        return False
+    output_dir = out_dir / rel
+    if not output_dir.is_dir():
+        return False
+
+    shutil.rmtree(output_dir)
+    return True
+
+
+def generate_module(
+    path: Path,
+    out_dir: Path,
+    *,
+    in_place: bool,
+) -> GeneratedModule | None:
+    module = read_module(path)
+    if module is None:
+        return None
+    components = collect_components(module, collect_protocols(module))
+    if not components:
+        return None
+    output_path = output_path_for(path, out_dir, in_place)
+    return GeneratedModule(
+        output_path=output_path,
+        import_path=module_import_path(path),
+        components=components,
+        public_imports=collect_public_imports(module),
+    )
+
+
+def contains_component_def(path: Path) -> bool:
+    return bool(component_stubs_for(path))
+
+
+def component_stubs_for(path: Path) -> list[ComponentStub]:
+    module = read_module(path)
+    if module is None:
+        return []
+    return collect_components(module, collect_protocols(module))
+
+
+def module_import_path(path: Path) -> str:
+    module_path = path.with_suffix("") if path.suffix == ".py" else path
+    try:
+        module_path = module_path.resolve().relative_to(Path.cwd().resolve())
+    except ValueError:
+        pass
+    return ".".join(module_path.parts)
+
+
+def render_stub(
+    components: list[ComponentStub],
+    public_imports: list[ImportStub] | None = None,
+    generated_import_paths: set[str] | None = None,
+) -> str:
+    imports = collect_stub_imports(components)
+    public_imports = public_imports or []
+    generated_import_paths = generated_import_paths or set()
+    public_import_lines = render_public_imports(public_imports, generated_import_paths)
+    lines = ["from __future__ import annotations", ""]
+    import_lines = format_imports([*imports, *public_import_lines])
+    if import_lines:
+        lines.extend([*import_lines, ""])
+    for component in components:
+        lines.extend(render_component(component))
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_public_imports(
+    public_imports: list[ImportStub],
+    generated_import_paths: set[str],
+) -> list[str]:
+    lines: list[str] = []
+    for import_stub in public_imports:
+        import_path = f"{import_stub.module}.{import_stub.name}"
+        if import_path in generated_import_paths:
+            lines.append(
+                f"from {import_stub.module} import {import_stub.name} "
+                f"as {import_stub.export_name}"
+            )
+    return lines
+
+
+def format_imports(imports: list[str]) -> list[str]:
+    stdlib = sorted(line for line in imports if is_stdlib_import(line))
+    relative = sorted(line for line in imports if line.startswith("from ."))
+    absolute = sorted(
+        line
+        for line in imports
+        if line not in stdlib and line not in relative
+    )
+    sections = [stdlib, absolute, relative]
+    lines: list[str] = []
+    for section in sections:
+        if not section:
+            continue
+        if lines:
+            lines.append("")
+        lines.extend(section)
+    return lines
+
+
+def is_stdlib_import(line: str) -> bool:
+    return line.startswith("from collections.") or line.startswith("from typing ")
+
+
+def collect_stub_imports(components: list[ComponentStub]) -> list[str]:
+    external_types = {
+        field.external_type for component in components for field in component.fields
+    }
+    imports = []
+    if any("Callable" in external_type for external_type in external_types):
+        imports.append("from collections.abc import Callable")
+    if components or "Any" in external_types:
+        imports.append("from typing import Any")
+    if components:
+        imports.append("from taut import runtime")
+    if any("reactive." in external_type for external_type in external_types):
+        imports.append("from taut import reactive")
+    return imports
+
+
+def write_package_exports(
+    modules: list[GeneratedModule],
+    source_paths: list[Path],
+    out_dir: Path,
+) -> None:
+    packages = package_marker_dirs(modules, source_paths, out_dir)
+    components_by_module = {
+        module.import_path: {component.name for component in module.components}
+        for module in modules
+    }
+    generated_modules = {module.import_path for module in modules}
+    attrs_by_package = public_attrs_by_package(modules)
+
+    for package_dir in sorted(packages):
+        marker = package_dir / "__init__.pyi"
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        source_init_path = source_init_for_marker(package_dir, out_dir)
+        marker.write_text(
+            render_init_stub(
+                source_init_path,
+                components_by_module,
+                generated_modules,
+                attrs_by_package.get(module_import_path(source_init_path.parent), set()),
+            ),
+            encoding="utf-8",
+        )
+
+
+def public_attrs_by_package(modules: list[GeneratedModule]) -> dict[str, set[str]]:
+    attrs_by_package: dict[str, set[str]] = {}
+    for module in modules:
+        package = module_import_path(Path(*module.import_path.split(".")[:-1]))
+        if not package:
+            continue
+        for import_stub in module.public_imports:
+            if import_stub.module == package:
+                attrs_by_package.setdefault(package, set()).add(import_stub.export_name)
+    return attrs_by_package
+
+
+def package_marker_dirs(
+    modules: list[GeneratedModule],
+    source_paths: list[Path],
+    out_dir: Path,
+) -> set[Path]:
+    package_dirs: set[Path] = set()
+    out_dir = out_dir.resolve()
+    for module in modules:
+        directory = module.output_path.parent.resolve()
+        while directory != out_dir and out_dir in directory.parents:
+            package_dirs.add(directory)
+            directory = directory.parent
+
+    for init_path in source_paths:
+        if init_path.name != "__init__.py":
+            continue
+        try:
+            package_dirs.add(output_path_for(init_path, out_dir, in_place=False).parent)
+        except ValueError:
+            pass
+    return package_dirs
+
+
+def source_init_for_marker(package_dir: Path, out_dir: Path) -> Path:
+    rel = package_dir.resolve().relative_to(out_dir.resolve())
+    return Path.cwd() / rel / "__init__.py"
+
+
+def render_init_stub(
+    source_init_path: Path,
+    components_by_module: dict[str, set[str]],
+    generated_modules: set[str],
+    package_attrs: set[str] | None = None,
+) -> str:
+    reexports: list[str] = []
+    functions: list[str] = []
+    attrs = sorted(package_attrs or set())
+    module = read_module(source_init_path)
+
+    package_import_path = module_import_path(source_init_path.parent)
+    if module is not None:
+        for node in module.body:
+            if isinstance(node, ast.ImportFrom) and node.module is not None:
+                import_path = resolve_import_from(source_init_path, node)
+                component_names = components_by_module.get(import_path)
+                module_ref = marker_import_ref(package_import_path, import_path)
+                for alias in node.names:
+                    export_name = alias.asname or alias.name
+                    if component_names and alias.name in component_names:
+                        reexports.append(
+                            f"from {module_ref} import {alias.name} as {export_name}"
+                        )
+                    elif f"{import_path}.{alias.name}" in generated_modules:
+                        reexports.append(
+                            f"from {module_ref} import {alias.name} as {export_name}"
+                        )
+            elif isinstance(node, ast.FunctionDef) and is_public_name(node.name):
+                functions.append(render_function_stub(node))
+
+    reexports.extend(
+        f"from . import {name} as {name}"
+        for name in attrs
+        if f"{package_import_path}.{name}" in generated_modules
+    )
+    imports = (
+        ["from typing import Any"]
+        if any_function_uses_any(functions)
+        else []
+    )
+    import_lines = format_imports([*imports, *reexports])
+    sections = [["from __future__ import annotations"], import_lines, functions]
+    lines = [line for section in sections if section for line in (*section, "")]
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def is_public_name(name: str) -> bool:
+    return not name.startswith("_")
+
+
+def render_function_stub(node: ast.FunctionDef) -> str:
+    returns = ast.unparse(node.returns) if node.returns is not None else "Any"
+    return f"def {node.name}({ast.unparse(node.args)}) -> {returns}: ..."
+
+
+def any_function_uses_any(functions: list[str]) -> bool:
+    return any(" -> Any:" in function for function in functions)
+
+
+def resolve_import_from(source_path: Path, node: ast.ImportFrom) -> str:
+    if node.level == 0:
+        return node.module or ""
+
+    package_path = source_path.parent
+    for _ in range(node.level - 1):
+        package_path = package_path.parent
+    package_import_path = module_import_path(package_path)
+    if not node.module:
+        return package_import_path
+    return f"{package_import_path}.{node.module}"
+
+
+def marker_import_ref(package_import_path: str, import_path: str) -> str:
+    package_parts = package_import_path.split(".")
+    import_parts = import_path.split(".")
+    common = 0
+    for package_part, import_part in zip(package_parts, import_parts):
+        if package_part != import_part:
+            break
+        common += 1
+
+    up_levels = len(package_parts) - common
+    remainder = ".".join(import_parts[common:])
+    return "." * (up_levels + 1) + remainder