glance-widgets-sdk 1.0.0__tar.gz

glance_widgets_sdk-1.0.0/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 Glance Widgets
+
+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.

glance_widgets_sdk-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+prune tests
+prune scripts

glance_widgets_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: glance-widgets-sdk
+Version: 1.0.0
+Summary: SDK for generating Glance Widgets API responses
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == "dev"
+Dynamic: license-file
+
+# Python SDK
+
+Layer constructors return a `Composite`: `{layers, data}`. Declarations contain only id, type and dataPath; the addressed objects contain layout, content and style. Merge layer results and chart components with the same merge function, then finalize with toResponse (to_response in snake_case APIs). An explicit dataPath chooses the object location; otherwise it is derived from id.
+
+`Matrix.to_part()` returns `{content: MatrixData}`. Place it with `place` / `Place` to give its node a frame and data path. The node's `content` holds `pixels`, `default`, `batch` and `layout`; matrix `style` is empty. Image and image-backed icon nodes use `content.url`. Bind an editor layer to a partial node in `data` without adding a remote declaration. Omitted or null values keep the saved editor value; objects merge field by field, arrays replace, and a supplied frame replaces the whole frame and must include width and height. Each response starts from the saved configuration.
+
+Pure Python 3.9+, using only the standard library.
+
+```sh
+python3 -m pip install glance-widgets-sdk
+```
+
+```python
+import json
+from glance_widgets import Box, merge, pixel_text_root, pixel_progress_bar, place, to_response
+
+canvas = {"width": 338, "height": 158}
+root = pixel_text_root("12:30", {"canvas": canvas, "theme": "led"})
+frame = Box.canvas(canvas).sub(0.1, 0.75, 0.8, 0.15).to_frame()
+bar = pixel_progress_bar(65, {"canvas": canvas, "frame": frame})
+badge = place(bar, {"id": "progress", "frame": frame, "path": "data.progress"})
+response = to_response(merge(root, badge))
+body = json.dumps(response, ensure_ascii=False, separators=(",", ":"))
+```
+
+API functions and methods use `snake_case`: `to_response`, `labeled_pixel_ring_progress`,
+`Matrix.to_part()`, `Box.from_pt()`. Arguments and returned protocol objects are
+dictionaries; their field names retain the TS/protocol spelling (`fontSizeRatio`,
+`dataPath`, `onConflict`, etc.). `Box.canvas(canvas)` creates a layout box.
+`themes["led"]` selects a theme, and custom pixel fonts use `define_font()`.
+
+See the [shared guide](../../docs/guide.md) for options and composition rules.
+
+Fonts, icons, validation schemas and the measured text advance table are bundled
+as package data. Regenerate them from the checked-in TS blueprint/spec with:
+
+```sh
+python3 sdks/python/scripts/generate_data.py
+```
+
+This development command needs the TypeScript SDK's installed compiler. The
+Python package itself does not invoke Node or depend on the repository layout.
+
+Use `layer_path(id)` for the derived node path, and `validate_layer_node(node, type)` to validate a partial editor node before returning it.

glance_widgets_sdk-1.0.0/README.md

@@ -0,0 +1,44 @@
+# Python SDK
+
+Layer constructors return a `Composite`: `{layers, data}`. Declarations contain only id, type and dataPath; the addressed objects contain layout, content and style. Merge layer results and chart components with the same merge function, then finalize with toResponse (to_response in snake_case APIs). An explicit dataPath chooses the object location; otherwise it is derived from id.
+
+`Matrix.to_part()` returns `{content: MatrixData}`. Place it with `place` / `Place` to give its node a frame and data path. The node's `content` holds `pixels`, `default`, `batch` and `layout`; matrix `style` is empty. Image and image-backed icon nodes use `content.url`. Bind an editor layer to a partial node in `data` without adding a remote declaration. Omitted or null values keep the saved editor value; objects merge field by field, arrays replace, and a supplied frame replaces the whole frame and must include width and height. Each response starts from the saved configuration.
+
+Pure Python 3.9+, using only the standard library.
+
+```sh
+python3 -m pip install glance-widgets-sdk
+```
+
+```python
+import json
+from glance_widgets import Box, merge, pixel_text_root, pixel_progress_bar, place, to_response
+
+canvas = {"width": 338, "height": 158}
+root = pixel_text_root("12:30", {"canvas": canvas, "theme": "led"})
+frame = Box.canvas(canvas).sub(0.1, 0.75, 0.8, 0.15).to_frame()
+bar = pixel_progress_bar(65, {"canvas": canvas, "frame": frame})
+badge = place(bar, {"id": "progress", "frame": frame, "path": "data.progress"})
+response = to_response(merge(root, badge))
+body = json.dumps(response, ensure_ascii=False, separators=(",", ":"))
+```
+
+API functions and methods use `snake_case`: `to_response`, `labeled_pixel_ring_progress`,
+`Matrix.to_part()`, `Box.from_pt()`. Arguments and returned protocol objects are
+dictionaries; their field names retain the TS/protocol spelling (`fontSizeRatio`,
+`dataPath`, `onConflict`, etc.). `Box.canvas(canvas)` creates a layout box.
+`themes["led"]` selects a theme, and custom pixel fonts use `define_font()`.
+
+See the [shared guide](../../docs/guide.md) for options and composition rules.
+
+Fonts, icons, validation schemas and the measured text advance table are bundled
+as package data. Regenerate them from the checked-in TS blueprint/spec with:
+
+```sh
+python3 sdks/python/scripts/generate_data.py
+```
+
+This development command needs the TypeScript SDK's installed compiler. The
+Python package itself does not invoke Node or depend on the repository layout.
+
+Use `layer_path(id)` for the derived node path, and `validate_layer_node(node, type)` to validate a partial editor node before returning it.

glance_widgets_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "glance-widgets-sdk"
+version = "1.0.0"
+requires-python = ">=3.9"
+description = "SDK for generating Glance Widgets API responses"
+readme = "README.md"
+license = { text = "MIT" }
+
+[project.optional-dependencies]
+dev = ["build>=1"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+glance_widgets = ["data/*.json", "data/fonts/*.json"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

glance_widgets_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

glance_widgets_sdk-1.0.0/src/glance_widgets/__init__.py

@@ -0,0 +1,138 @@
+"""Glance Widgets SDK: native Python builders for protocol v1."""
+
+from .color import (
+    parse_color,
+    format_color,
+    normalize_color,
+    is_app_color,
+    rgb,
+    with_alpha,
+    mix_colors,
+)
+from .geometry import (
+    Box,
+    require_canvas,
+    resolve_frame,
+    fit_matrix,
+    cell_rect,
+    column_boundary,
+    row_boundary,
+    to_ratio_rect,
+    solve_grid,
+    GAP_MODE_RATIOS,
+    FRAME_DECIMALS,
+)
+from .matrix import Matrix, EMPTY, DEFAULT_PIXEL_BASE, BATCH_MIN_OCCURRENCES
+from .font import (
+    PixelFont,
+    define_font,
+    get_font,
+    resolve_font,
+    measure_text,
+    layout_text,
+    FONT_3X5,
+    FONT_5X7,
+    DEFAULT_FONT_NAME,
+    DEFAULT_LETTER_SPACING,
+    DEFAULT_LINE_SPACING,
+    ANCHOR_BOX_WIDTH,
+)
+from .text_matrix import text_matrix
+from .themes import (
+    themes,
+    get_theme,
+    theme_options,
+    OFF_PIXEL_OPACITY,
+    ROOT_RING_OPACITY_THRESHOLD,
+)
+from .icons import has_icon, icon_names, icon_glyph, DEFAULT_ICON_NAME
+from .layers import (
+    text,
+    line,
+    horizontal_line,
+    vertical_line,
+    shape,
+    icon,
+    image,
+    curve,
+    TEXT_DEFAULTS,
+    LINE_DEFAULTS,
+    SHAPE_DEFAULTS,
+    ICON_DEFAULTS,
+    IMAGE_DEFAULTS,
+    CURVE_DEFAULTS,
+)
+from .output import layer_path, layer_id, nest_at_path, merge, place, empty_root, to_response
+from .protocol import (
+    validate,
+    resolve_data_path,
+    GlanceValidationError,
+    PROTOCOL_VERSION,
+    MAX_RESPONSE_BYTES,
+    MAX_MATRIX_CELLS,
+    LAYER_ID_PREFIX,
+    MAX_SAFE_NATIVE_INTEGER,
+    DATA_PATH_PATTERN,
+    CELL_ASPECT_RATIO_MIN,
+    CELL_ASPECT_RATIO_MAX,
+    EDGE_INSET_RATIO_LIMIT,
+    GAP_RATIO_MAX,
+    FRAME_SIZE_MIN,
+    FRAME_SIZE_MAX,
+    SHAPE_MIN_SIZE_PT,
+)
+from .raster import RASTER_MAX_EXTENT, RASTER_MAX_COORDINATE, ARC_DIRECTION_SCALE
+from .signature import (
+    sign,
+    verify_signature,
+    TIMESTAMP_HEADER,
+    SIGNATURE_HEADER,
+    DEFAULT_SIGNATURE_TOLERANCE_MS,
+)
+from .pixelate import pixelate, DEFAULT_ALPHA_THRESHOLD
+from .pixel_progress import (
+    pixel_progress_bar,
+    labeled_pixel_progress_bar,
+    pixel_ring_progress,
+    labeled_pixel_ring_progress,
+    PIXEL_PROGRESS_BAR_DEFAULTS,
+    LABELED_PIXEL_PROGRESS_BAR_DEFAULTS,
+    PIXEL_RING_PROGRESS_DEFAULTS,
+    LABELED_PIXEL_RING_PROGRESS_DEFAULTS,
+)
+from .modern import (
+    progress_bar,
+    ring_progress,
+    bar_chart,
+    battery,
+    signal,
+    arc_pieces,
+    PROGRESS_BAR_DEFAULTS,
+    RING_PROGRESS_DEFAULTS,
+    BAR_CHART_DEFAULTS,
+    BATTERY_DEFAULTS,
+    SIGNAL_DEFAULTS,
+    BAD_LEVEL,
+    WARN_LEVEL,
+)
+from .status import (
+    status_strip,
+    labeled_status_strip,
+    STATUS_STRIP_DEFAULTS,
+    LABELED_STATUS_STRIP_DEFAULTS,
+)
+from .pixel_text import pixel_text_panel, pixel_text_root, PIXEL_TEXT_DEFAULTS
+from ._shared import STATUS_COLORS, DEFAULT_THEME_NAME, percent_label
+from .heatmap import (
+    heatmap,
+    calendar_heatmap,
+    labeled_calendar_heatmap,
+    HEATMAP_DEFAULTS,
+    CALENDAR_HEATMAP_DEFAULTS,
+    LABELED_CALENDAR_HEATMAP_DEFAULTS,
+)
+from .pixel_bar_chart import pixel_bar_chart, PIXEL_BAR_CHART_DEFAULTS
+from .line_chart import line_chart, area_chart, sparkline, LINE_CHART_DEFAULTS
+from .stat import stat, STAT_DEFAULTS
+
+from .protocol import validate_layer_node

glance_widgets_sdk-1.0.0/src/glance_widgets/_opt.py

@@ -0,0 +1,6 @@
+"""Option lookup where None means unset (TypeScript `??`)."""
+
+
+def opt(options, key, default=None):
+    value = None if options is None else options.get(key)
+    return default if value is None else value

glance_widgets_sdk-1.0.0/src/glance_widgets/_shared.py

@@ -0,0 +1,225 @@
+"""Internal component layout and formatting helpers."""
+
+import json
+import math
+from pathlib import Path
+import re
+from ._opt import opt
+from .color import clamp, js_round
+from .geometry import Box, require_canvas, resolve_frame, solve_grid
+from .layers import text
+from .themes import get_theme
+
+DEFAULT_THEME_NAME = "lcd"
+STATUS_COLORS = dict(good="#34C759", warn="#FF9F0A", bad="#FF453A", neutral="#8E8E93")
+TEXT_LINE_HEIGHT = 1.2
+LABEL_BOX_LINES = 1.5
+LABEL_GAP_EM = 0.4
+_advances = json.loads((Path(__file__).parent / "data/text-advances.json").read_text())
+
+
+def resolve_theme(theme=None):
+    return (
+        get_theme(DEFAULT_THEME_NAME if theme is None else theme)
+        if theme is None or isinstance(theme, str)
+        else theme
+    )
+
+
+def resolve_area(frame, canvas):
+    if frame is None:
+        return Box.canvas(canvas)
+    return (
+        Box(frame.left, frame.top, frame.width, frame.height, canvas)
+        if isinstance(frame, Box)
+        else Box.from_frame(frame, canvas)
+    )
+
+
+def emitted_region(box, canvas):
+    frame = box.to_frame()
+    return dict(frame=frame, rect=resolve_frame(frame, canvas))
+
+
+def region_of(options, what):
+    canvas, frame = options.get("canvas"), options.get("frame")
+    if canvas is None:
+        if isinstance(frame, Box) and frame._canvas is not None:
+            return frame.to_pt()
+        if frame is not None:
+            raise ValueError(what + ": a frame needs a canvas")
+        return None
+    return emitted_region(resolve_area(frame, require_canvas(canvas, what)), canvas)[
+        "rect"
+    ]
+
+
+def plan_grid(region, size, theme, what):
+    if region is None:
+        if size.get("columns") is None or size.get("rows") is None:
+            raise ValueError(what + ": grid needs both counts without canvas")
+        return dict(
+            columns=size["columns"], rows=size["rows"], layout=dict(theme["layout"])
+        )
+    return solve_grid(
+        dict(
+            region=region,
+            **{k: v for k, v in size.items() if v is not None},
+            gapMode=theme["layout"]["gapMode"],
+            clampAspect=True,
+        )
+    )
+
+
+def pixel_looks(theme, colors=None):
+    colors = colors or {}
+    off = (
+        {**theme["default"], "color": colors["off"]}
+        if colors.get("off")
+        else theme["default"]
+    )
+    return dict(
+        on=opt(colors, "on", theme["palette"]["on"]),
+        off="empty" if "off" in colors and colors["off"] is None else off,
+    )
+
+
+def text_advance_em(content):
+    return (
+        sum(
+            (
+                _advances["ascii"][ord(c) - 32]
+                if 32 <= ord(c) < 127
+                else _advances["extra"].get(c, 1000)
+            )
+            + 40
+            for c in content
+        )
+        / 1000
+    )
+
+
+def text_advance_pt(content, font_pt):
+    return text_advance_em(content) * font_pt
+
+
+def estimate_text_width_pt(content, font_pt):
+    return text_advance_em(content) * 1.05 * font_pt + 1
+
+
+def font_pt_for_width(content, width):
+    return max(0, width - 1) / max(1e-9, text_advance_em(content) * 1.05)
+
+
+def text_box_height_pt(font_pt, lines=1):
+    return lines * 1.2 * font_pt + 1
+
+
+def font_pt_of(ratio, canvas):
+    return ratio * min(canvas["width"], canvas["height"])
+
+
+def font_ratio_of(pt, canvas):
+    return clamp(pt / min(canvas["width"], canvas["height"]), 0.02, 0.28)
+
+
+def resolve_identity(options, default_id, what):
+    identity = opt(options, "id", default_id)
+    path = opt(options, "path")
+    if path is None and not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", identity):
+        raise ValueError(what + ": non-identifier id needs an explicit path")
+    return identity, path if path is not None else "data." + identity
+
+
+def to_fixed(value, decimals):
+    """Round the exact IEEE double, with decimal ties away from zero (ECMAScript)."""
+    if isinstance(decimals, bool) or not isinstance(decimals, (int, float)):
+        raise ValueError("decimals must be a number in 0..100")
+    if decimals != decimals:  # NaN -> 0 (ToIntegerOrInfinity)
+        decimals = 0
+    if not math.isfinite(decimals) or not 0 <= math.trunc(decimals) <= 100:
+        raise ValueError("decimals must be in 0..100")
+    decimals = math.trunc(decimals)
+    value = float(value)
+    if value != value:
+        return "NaN"
+    if math.isinf(value):
+        return "Infinity" if value > 0 else "-Infinity"
+    if abs(value) >= 1e21:
+        return repr(value)
+    numerator, denominator = abs(value).as_integer_ratio()
+    scaled = numerator * 10**decimals
+    rounded, remainder = divmod(scaled, denominator)
+    if remainder * 2 >= denominator:
+        rounded += 1
+    digits = str(rounded).rjust(decimals + 1, "0")
+    result = digits[:-decimals] + "." + digits[-decimals:] if decimals else digits
+    return ("-" if value < 0 else "") + result
+
+
+def format_number(value, decimals):
+    result = to_fixed(value, decimals)
+    return to_fixed(0, decimals) if float(result) == 0 else result
+
+
+def default_decimals(*values):
+    return 0 if all(float(v).is_integer() for v in values) else 1
+
+
+def fraction_of(value, minimum, maximum):
+    if (
+        not isinstance(value, (int, float))
+        or isinstance(value, bool)
+        or not math.isfinite(value)
+    ):
+        raise ValueError("Value must be finite")
+    return (
+        clamp((value - minimum) / (maximum - minimum), 0, 1) if maximum > minimum else 0
+    )
+
+
+def require_range(what, minimum, maximum):
+    valid_numbers = all(
+        isinstance(value, (int, float))
+        and not isinstance(value, bool)
+        and math.isfinite(value)
+        for value in (minimum, maximum)
+    )
+    if not valid_numbers or maximum <= minimum:
+        raise ValueError(what + ": max must be greater than min")
+
+
+def require_positive_integer(what, name, value):
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not math.isfinite(value)
+        or int(value) != value
+        or value < 1
+    ):
+        raise ValueError(what + ": " + name + " must be a positive integer")
+
+
+def label_layer(s):
+    style = dict(
+        color=s["color"],
+        textOpacity=s["opacity"],
+        fontSizeRatio=s["fontSizeRatio"],
+        horizontalAlignment=s["horizontal"],
+        verticalAlignment=s["vertical"],
+    )
+    if "fontWeight" in s:
+        style["fontWeight"] = s["fontWeight"]
+    return text(
+        dict(
+            id=s["id"],
+            frame=s["box"],
+            text=s["content"],
+            zIndex=s["zIndex"],
+            style=style,
+        )
+    )
+
+
+def percent_label(fraction):
+    return str(js_round(fraction * 100)) + "%"

glance_widgets_sdk-1.0.0/src/glance_widgets/color.py

@@ -0,0 +1,95 @@
+"""Protocol colors use alpha first: #AARRGGBB."""
+
+import math
+import re
+
+
+def js_round(value):
+    if not math.isfinite(value):  # NaN/Infinity pass through like Math.round
+        return value
+    return math.floor(value + 0.5)
+
+
+def js_div(a, b):
+    """a / b with IEEE results (Infinity/NaN) instead of ZeroDivisionError."""
+    if b == 0:
+        if a == 0 or a != a:
+            return math.nan
+        return math.copysign(math.inf, a) * math.copysign(1.0, b)
+    return a / b
+
+
+def clamp(value, low, high):
+    if value != value:  # NaN propagates like Math.min/Math.max
+        return value
+    return min(high, max(low, value))
+
+
+JS_WHITESPACE = "\u0009\u000a\u000b\u000c\u000d\u0020\u00a0\u1680" \
+    "\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a" \
+    "\u2028\u2029\u202f\u205f\u3000\ufeff"
+
+
+def parse_color(color):
+    if not isinstance(color, str):
+        raise ValueError("Invalid color: expected #RGB, #RRGGBB or #AARRGGBB")
+    color = color.strip(JS_WHITESPACE)
+    if not re.fullmatch(
+        r"#?(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})", color
+    ):
+        raise ValueError("Invalid color: expected #RGB, #RRGGBB or #AARRGGBB")
+    code = color.lstrip("#")
+    if len(code) == 3:
+        code = "".join(c * 2 for c in code)
+    if len(code) == 6:
+        code = "FF" + code
+    return dict(
+        zip(("a", "r", "g", "b"), (int(code[i : i + 2], 16) for i in range(0, 8, 2)))
+    )
+
+
+def _js_number_text(v):
+    if isinstance(v, float) and v != v:
+        return "NaN"
+    if isinstance(v, float) and math.isinf(v):
+        return "Infinity" if v > 0 else "-Infinity"
+    return str(v)
+
+
+def format_color(color):
+    def channel(v):
+        if (
+            isinstance(v, bool)
+            or not isinstance(v, (int, float))
+            or not math.isfinite(v)
+        ):
+            raise ValueError("Invalid color channel " + _js_number_text(v))
+        return clamp(js_round(v), 0, 255)
+
+    values = {k: channel(color[k]) for k in ("r", "g", "b", "a")}
+    code = "".join(f"{values[k]:02X}" for k in ("r", "g", "b"))
+    return "#" + (f"{values['a']:02X}" if values["a"] != 255 else "") + code
+
+
+def normalize_color(color):
+    return format_color(parse_color(color))
+
+
+def is_app_color(color):
+    return isinstance(color, str) and bool(
+        re.fullmatch(r"#?(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})", color)
+    )
+
+
+def rgb(r, g, b, alpha=1):
+    return format_color(dict(r=r, g=g, b=b, a=alpha * 255))
+
+
+def with_alpha(color, alpha):
+    return format_color({**parse_color(color), "a": alpha * 255})
+
+
+def mix_colors(start, end, t):
+    a, b = parse_color(start), parse_color(end)
+    t = clamp(t, 0, 1)
+    return format_color({k: a[k] + (b[k] - a[k]) * t for k in a})