tealui 0.3.0__py3-none-any.whl

tealui/__init__.py

@@ -0,0 +1,43 @@
+"""A tiny, clean, pythonic UI library."""
+from . import tags as _tags
+from .core import El, Tag, Raw, render
+from .tags import *
+from .look import use, using, current, r, make_look, check_look, look_problems
+from .looks import (TEAL, PAPER, SLATE, INDIGO, MIDNIGHT, LEDGER, ENTERPRISE, CONTRAST,
+                    FOREST, SUNSET, NORDIC, SOFT, TERMINAL, BRUTAL)
+from .theme import with_accent, with_fonts
+from .icons import register_icon
+from .page import Page
+from .ui.foundation import Icon, Button, Badge, Avatar, Card, Kbd
+from .ui.charts import Sparkline, AreaChart
+from .ui.data import Delta, Stat, Progress, Table, BarList
+from .ui.nav import Tabs, Breadcrumb
+from .ui.shell import NavItem, Sidebar, Topbar, PageHeader, DarkToggle, Shell
+from .ui.forms import Segmented, SearchBox, TagFilter, tag_show
+from .ui.content import SiteHeader, Prose, CodeBlock, Callout
+from .ui.forms2 import TextInput, SelectBox, Checkbox, Switch, Field, TextBox, RadioGroup
+from .ui.overlay import Modal, Dropdown, Toaster, toast_js
+from .ui.mobile import AppScreen, LargeTitle, ListGroup, ListRow, TabBar
+from .ui.article import Toc, ReadingProgress, ArticleHeader, ShareBar, PostCard, Pager, DocsNav
+use(TEAL)
+__all__ = list(dict.fromkeys([
+    "El", "Tag", "Raw", "render", "use", "using", "current", "r",
+    "TEAL", "PAPER", "SLATE", "INDIGO", "MIDNIGHT", "LEDGER", "ENTERPRISE", "CONTRAST",
+    "FOREST", "SUNSET", "NORDIC", "SOFT", "TERMINAL", "BRUTAL",
+    "make_look", "check_look", "look_problems", "with_accent", "Page", "Icon",
+    "Button", "Badge", "Avatar", "Card", "Kbd",
+    "Sparkline", "AreaChart", "Delta", "Stat", "Progress", "Table", "BarList",
+    "Tabs", "Breadcrumb",
+    "NavItem", "Sidebar", "Topbar", "PageHeader", "DarkToggle", "Shell",
+    "Segmented", "SearchBox",
+    "SiteHeader", "Prose", "CodeBlock", "Callout",
+    "TextInput", "SelectBox", "Checkbox", "Switch", "Field",
+    "Modal",
+    "Dropdown", "Toaster", "toast_js",
+    "Toc", "ReadingProgress", "ArticleHeader", "ShareBar", "PostCard", "Pager", "DocsNav",
+    "AppScreen", "LargeTitle", "ListGroup", "ListRow", "TabBar",
+    "with_fonts", "register_icon",
+    "TextBox", "RadioGroup", "TagFilter", "tag_show",
+    *_tags.__all__
+]))
+__version__ = "0.3.0"

tealui/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tealui/cli.py

@@ -0,0 +1,173 @@
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from .theme import tailwind_input
+from .versions import TAILWIND_RANGE, ALPINE_RANGE, HTMX_RANGE
+from .devtools import _run_test, _run_export
+from . import toolchain
+from . import lookcli
+
+_FONTS = ("inter.woff2", "serif.woff2", "serif-italic.woff2", "mono.woff2")
+
+
+def _fonts_dir():
+    return Path(__file__).resolve().parent / "fonts"
+
+
+def _write_input_and_fonts(out, srcs, input_path, looks=()):
+    out_dir = Path(out).parent
+    out_dir.mkdir(parents=True, exist_ok=True)
+    abs_paths = [Path(p).resolve().as_posix() for p in (srcs or [os.getcwd()])]
+    if looks:
+        # Third-party looks may live outside the scanned folders (site-packages): list their classes in a file.
+        looks_txt = out_dir / "tealui.looks.txt"
+        looks_txt.write_text(lookcli.classes(looks), encoding="utf-8")
+        abs_paths.append(looks_txt.resolve().as_posix())
+        print(f"included {len(looks)} look(s): {', '.join(x.get('name', '?') for x in looks)}")
+    if input_path is None:
+        input_path = out_dir / "tealui.input.css"
+    input_path = Path(input_path)
+    input_path.parent.mkdir(parents=True, exist_ok=True)
+    input_path.write_text(tailwind_input(*abs_paths), encoding="utf-8")
+    fonts_out = out_dir / "fonts"
+    fonts_out.mkdir(parents=True, exist_ok=True)
+    for name in _FONTS:
+        shutil.copyfile(_fonts_dir() / name, fonts_out / name)
+    return input_path
+
+
+def _run_css(args):
+    input_path = _write_input_and_fonts(args.out, args.src, args.input, lookcli.build_looks(args.look))
+    print(f"wrote {input_path}")
+    print(f"copied fonts to {Path(args.out).parent / 'fonts'}")
+    print(f"next: tealui build {args.out} --src <your source folders>")
+    print(f"or run any Tailwind v4 CLI: tailwindcss -i {input_path} -o {args.out} --minify")
+    return 0
+
+
+def _run_build(args):
+    cache = toolchain.cache_root(args.cache)
+    input_path = _write_input_and_fonts(args.out, args.src, None, lookcli.build_looks(args.look))
+    exe = toolchain.ensure_tailwind(cache, TAILWIND_RANGE)
+    if args.alpine:
+        alpine_path = toolchain.ensure_alpine(cache, ALPINE_RANGE)
+        dest = Path(args.alpine)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(alpine_path, dest)
+        version = toolchain.installed(cache, "alpine", ALPINE_RANGE)
+        print(f"copied Alpine {version} to {args.alpine}")
+    if args.htmx:
+        htmx_path = toolchain.ensure_htmx(cache, HTMX_RANGE)
+        dest = Path(args.htmx)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(htmx_path, dest)
+        version = toolchain.installed(cache, "htmx", HTMX_RANGE)
+        print(f"copied HTMX {version} to {args.htmx}")
+    cmd = [str(exe), "-i", str(input_path), "-o", str(Path(args.out).resolve()), "--minify"]
+    if args.watch:
+        cmd.append("--watch")
+    return subprocess.run(cmd).returncode
+
+
+def _run_update(args):
+    cache = toolchain.cache_root(args.cache)
+    for name, major, ensure_fn in [("tailwind", TAILWIND_RANGE, toolchain.ensure_tailwind),
+                                   ("alpine", ALPINE_RANGE, toolchain.ensure_alpine),
+                                   ("htmx", HTMX_RANGE, toolchain.ensure_htmx)]:
+        before = toolchain.installed(cache, name, major)
+        ensure_fn(cache, major, update=True)
+        after = toolchain.installed(cache, name, major)
+        pkg_name = {"tailwind": "tailwindcss", "alpine": "alpinejs", "htmx": "htmx.org"}[name]
+        if before is None:
+            print(f"{pkg_name} installed {after}")
+        elif before != after:
+            print(f"{pkg_name} {before} -> {after}")
+        else:
+            print(f"{pkg_name} {after} (up to date)")
+    return 0
+
+
+def _run_versions(args):
+    cache = toolchain.cache_root(args.cache)
+    for pkg, name, major in [("tailwindcss", "tailwind", TAILWIND_RANGE), ("alpinejs", "alpine", ALPINE_RANGE), ("htmx.org", "htmx", HTMX_RANGE)]:
+        inst = toolchain.installed(cache, name, major)
+        if inst:
+            inst_str = f"installed {inst}"
+        else:
+            inst_str = "not installed"
+        try:
+            if pkg == "tailwindcss":
+                latest = toolchain.latest_tailwind(major)
+            else:
+                latest, _ = toolchain.npm_latest(pkg, major)
+            latest_str = latest or "unknown"
+        except toolchain.ToolchainError:
+            latest_str = "unknown"
+        print(f"{pkg}  {inst_str}  latest {latest_str}  tracking {major}.x")
+        try:
+            dist_tags = json.loads(toolchain._get(f"https://registry.npmjs.org/-/package/{pkg}/dist-tags"))
+            overall_latest = dist_tags.get("latest")
+            if overall_latest and not overall_latest.startswith(f"{major}."):
+                print(f"note: a newer major version exists ({overall_latest}); TealUI keeps tracking {major}.x until it has been tested")
+        except (toolchain.ToolchainError, json.JSONDecodeError, KeyError):
+            pass
+    return 0
+
+
+def main(argv=None):
+    """Run the tealui command line interface."""
+    parser = argparse.ArgumentParser(prog="tealui")
+    sub = parser.add_subparsers(dest="cmd")
+    css = sub.add_parser("css", help="write the Tailwind input file and copy fonts")
+    css.add_argument("out")
+    css.add_argument("--src", action="append", default=[])
+    css.add_argument("--input")
+    css.add_argument("--look", action="append", default=[], help="third-party look to include (module:NAME)")
+    build = sub.add_parser("build", help="write inputs, then run the Tailwind CLI")
+    build.add_argument("out")
+    build.add_argument("--src", action="append", default=[])
+    build.add_argument("--cache")
+    build.add_argument("--watch", action="store_true")
+    build.add_argument("--alpine")
+    build.add_argument("--htmx")
+    build.add_argument("--look", action="append", default=[], help="third-party look to include (module:NAME)")
+    upd = sub.add_parser("update", help="update the cached toolchain")
+    upd.add_argument("--cache")
+    ver = sub.add_parser("versions", help="show installed and latest versions")
+    ver.add_argument("--cache")
+    test = sub.add_parser("test", help="run the unit tests")
+    test.add_argument("--browser", action="store_true")
+    export = sub.add_parser("export", help="build wheel, sdist and source zip")
+    export.add_argument("outdir", nargs="?", default="dist")
+    export.add_argument("--no-test", action="store_true")
+    export.add_argument("--wheel-only", action="store_true")
+    lookcli.add_parsers(sub)
+    args = parser.parse_args(argv)
+    try:
+        if args.cmd == "css":
+            return _run_css(args)
+        if args.cmd == "build":
+            return _run_build(args)
+        if args.cmd == "update":
+            return _run_update(args)
+        if args.cmd == "versions":
+            return _run_versions(args)
+        if args.cmd == "test":
+            return _run_test(args)
+        if args.cmd == "export":
+            return _run_export(args)
+        if args.cmd in ("look", "looks"):
+            return lookcli.run(args)
+        parser.error("a subcommand is required")
+    except (toolchain.ToolchainError, ValueError, OSError) as e:
+        print(f"tealui: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tealui/core.py

@@ -0,0 +1,113 @@
+import html
+import re
+from typing import Any
+
+class Raw(str):
+    """Trusted markup, never escaped as child."""
+
+_VOID = frozenset("area base br col embed hr img input link meta source track wbr".split())
+
+def attr_name(key: str) -> str:
+    """Convert Python kwarg to HTML/Alpine attribute name."""
+    if any(c in key for c in "@:.-"):
+        if not re.fullmatch(r"[A-Za-z_:@][A-Za-z0-9_:.@-]*", key):
+            raise ValueError(f"bad attribute name: {key!r}")
+        return key
+    if key == "cls":
+        key = "class"
+    key = key.rstrip("_")
+    base, *mods = key.split("__")
+    if base.startswith("on_"):
+        base = "@" + base[3:]
+    elif base.startswith("bind_"):
+        base = ":" + base[5:]
+    parts = [p.replace("_", "-") for p in [base] + mods]
+    res = ".".join(parts)
+    if not re.fullmatch(r"[A-Za-z_:@][A-Za-z0-9_:.@-]*", res):
+        raise ValueError(f"bad attribute name: {res!r}")
+    return res
+
+def _freeze(x):
+    """Turn one-shot iterators (generators, map, zip...) into tuples so an element renders the same every time."""
+    if isinstance(x, (str, bytes, El)) or not hasattr(x, "__next__"):
+        if isinstance(x, list):
+            return [_freeze(i) for i in x]
+        return x
+    return tuple(_freeze(i) for i in x)
+
+def _flat(v):
+    for x in v:
+        if isinstance(x, (list, tuple)):
+            yield from _flat(x)
+        elif x is not None and x is not False and x != "":
+            yield str(x)
+
+_URL_ATTRS = frozenset(("href", "src", "action", "formaction", "poster", "xlink:href", "data", "background"))
+# SVG <set>/<animate> can write a URL into href through these attributes.
+_ANIM_ATTRS = frozenset(("to", "from", "by", "values"))
+
+def _bad_url(v: str) -> bool:
+    check = "".join(c for c in v if ord(c) > 32 and not c.isspace()).lower()
+    return check.startswith(("javascript:", "vbscript:")) or \
+        (check.startswith("data:") and not re.fullmatch(r"data:image/(png|jpe?g|gif|webp|avif)[;,].*", check))
+
+def _url_safe(k: str, v: str) -> str:
+    """Check URL safety for specific attributes."""
+    # bound attributes (bind_href) are dynamic and are not checked.
+    k = k.lower()
+    if k in _URL_ATTRS and _bad_url(v):
+        return "#"
+    if k in _ANIM_ATTRS and any(_bad_url(part) for part in v.split(";")):
+        return "#"
+    return v
+
+class El:
+    """An HTML element."""
+    def __init__(self, tag: str, *children: Any, **attrs: Any):
+        """Initialize the element with a tag, children, and attributes."""
+        if not re.fullmatch(r"[A-Za-z][A-Za-z0-9-]*", tag):
+            raise ValueError(f"bad tag name: {tag!r}")
+        if tag.lower() in _VOID and children:
+            raise ValueError(f"void element {tag!r} cannot have children")
+        self.tag, self.children, self.attrs = tag, tuple(_freeze(c) for c in children), attrs
+
+    def __str__(self) -> str:
+        """Render the element to HTML."""
+        is_void = self.tag.lower() in _VOID
+        # script/style children follow normal rules: str escaped, Raw not.
+        a = []
+        for k, v in self.attrs.items():
+            if v is False or v is None:
+                continue
+            name = attr_name(k)
+            if v is True:
+                a.append(f" {name}")
+            else:
+                if name == "class" and isinstance(v, (list, tuple)):
+                    v = " ".join(_flat(v))
+                    if not v:
+                        continue
+                sv = html.escape(str(v), quote=True)
+                sv = _url_safe(name, sv)
+                a.append(f' {name}="{sv}"')
+        o = f"<{self.tag}{''.join(a)}>"
+        if is_void:
+            return o
+        c = "".join(render(x) for x in self.children)
+        return f"{o}{c}</{self.tag}>"
+
+Tag = El
+
+def render(x: Any) -> str:
+    """Render any child value to HTML."""
+    if isinstance(x, Raw):
+        return x
+    if isinstance(x, str):
+        return html.escape(x, quote=True)
+    if isinstance(x, El):
+        return str(x)
+    if x is None or x is False:
+        return ""
+    if isinstance(x, (list, tuple)) or hasattr(x, "__next__"):
+        return "".join(render(i) for i in x)
+    return html.escape(str(x), quote=True)

tealui/devtools.py

@@ -0,0 +1,126 @@
+import hashlib
+import importlib.util
+import subprocess
+import sys
+import zipfile
+from pathlib import Path
+
+import tealui
+
+
+def _project_root(start=None):
+    """Walk up from start (or this file) to find the project root."""
+    p = Path(start) if start else Path(__file__).resolve().parent
+    for parent in [p] + list(p.parents):
+        if (parent / "pyproject.toml").is_file() and (parent / "tests").is_dir():
+            return parent
+    return None
+
+
+def _run_test(args):
+    root = _project_root()
+    if root is None:
+        print("tealui: tests are only available in a source checkout", file=sys.stderr)
+        return 2
+    res = subprocess.run([sys.executable, "-m", "unittest", "discover", "-s", "tests"], cwd=root)
+    if res.returncode != 0 or not getattr(args, "browser", False):
+        return res.returncode
+    compat = root / "tools" / "compat.py"
+    if not compat.is_file():
+        print("tealui: tools/compat.py not found", file=sys.stderr)
+        return 2
+    code = subprocess.run([sys.executable, str(compat)], cwd=root).returncode
+    for name in ("a11y_suite.py", "looks_suite.py"):
+        suite = root / "tools" / name
+        if code == 0 and suite.is_file():
+            code = subprocess.run([sys.executable, str(suite)], cwd=root).returncode
+    return code
+
+
+def _wheel_problems(path):
+    problems = []
+    required = {
+        "tealui/fonts/inter.woff2", "tealui/fonts/serif.woff2",
+        "tealui/fonts/serif-italic.woff2", "tealui/fonts/mono.woff2",
+        "tealui/fonts/LICENSES.txt", "tealui/icons-LICENSE.txt", "tealui/py.typed"
+    }
+    with zipfile.ZipFile(path) as zf:
+        names = set(zf.namelist())
+        for req in required:
+            if req not in names:
+                problems.append(f"missing {req}")
+        for name in names:
+            if name.startswith("tests/"):
+                problems.append(f"unexpected {name}")
+            if "__pycache__" in name:
+                problems.append(f"unexpected {name}")
+    return problems
+
+
+def _write_source_zip(root, outdir, version):
+    zip_path = Path(outdir) / f"tealui-{version}-src.zip"
+    prefix = f"tealui-{version}/"
+    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        for item in ["tealui", "pyproject.toml", "README.md"]:
+            p = root / item
+            if p.is_file():
+                zf.write(p, prefix + item)
+            elif p.is_dir():
+                for sub in p.rglob("*"):
+                    if sub.is_file() and "__pycache__" not in sub.parts and not sub.name.endswith(".pyc"):
+                        zf.write(sub, prefix + str(sub.relative_to(root)))
+        if (root / "LICENSE").is_file():
+            zf.write(root / "LICENSE", prefix + "LICENSE")
+    return zip_path
+
+
+def _describe(paths):
+    lines = []
+    for p in sorted(paths):
+        size_kb = p.stat().st_size / 1024
+        h = hashlib.sha256(p.read_bytes()).hexdigest()[:12]
+        lines.append(f"{size_kb:.1f} KB  {h}  {p}")
+    return lines
+
+
+def _run_export(args):
+    root = _project_root()
+    if root is None:
+        print("tealui: tests are only available in a source checkout", file=sys.stderr)
+        return 2
+    outdir = Path(args.outdir)
+    if not args.no_test and _run_test(type("A", (), {"browser": False})()) != 0:
+        print("tealui: tests failed, nothing exported", file=sys.stderr)
+        return 1
+    if importlib.util.find_spec("build") is None:
+        print("tealui: install the build tool first: pip install build", file=sys.stderr)
+        return 2
+    outdir.mkdir(parents=True, exist_ok=True)
+    cmd = [sys.executable, "-m", "build", "--outdir", str(outdir), str(root)]
+    if args.wheel_only:
+        cmd.insert(3, "--wheel")
+    if subprocess.run(cmd).returncode != 0:
+        print("tealui: build failed", file=sys.stderr)
+        return 1
+    return _finalize_export(outdir, root, args.wheel_only)
+
+
+def _finalize_export(outdir, root, wheel_only):
+    wheels = sorted(outdir.glob("*.whl"))
+    if not wheels:
+        print("tealui: build failed", file=sys.stderr)
+        return 1
+    problems = _wheel_problems(wheels[-1])
+    if problems:
+        for p in problems:
+            print(f"tealui: wheel problem: {p}", file=sys.stderr)
+        return 1
+    produced = [wheels[-1]]
+    if not wheel_only:
+        sdist = sorted(outdir.glob("*.tar.gz"))
+        if sdist:
+            produced.append(sdist[-1])
+        produced.append(_write_source_zip(root, outdir, tealui.__version__))
+    for line in _describe(produced):
+        print(line)
+    return 0