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.
