imagespec-designer 0.1.0__tar.gz

imagespec_designer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 eigger
+
+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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

imagespec_designer-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.ko.md
+recursive-include docs *.md

imagespec_designer-0.1.0/NOTICE

@@ -0,0 +1,12 @@
+Third-party and adapted material
+
+imagespec_designer/document.py includes geometry mappings and starter
+specifications adapted from hass-ble-esl's BLE ESL designer, copyright
+(c) 2025 eigger. The adapted code is distributed under the MIT License;
+see LICENSE.
+
+imagespec_designer/web/icons.json is a modified icon-name-to-glyph map derived
+from Material Design Icons metadata by Pictogrammers, Austin Andrews, and
+contributors. The map is licensed under Apache License 2.0; see
+licenses/Apache-2.0.txt and https://github.com/Templarian/MaterialDesign-Webfont.
+This package includes the map only; it does not include the icon font.

imagespec_designer-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: imagespec-designer
+Version: 0.1.0
+Summary: Framework-neutral visual editor and document tools for imagespec layouts
+Author: eigger
+License-Expression: MIT AND Apache-2.0
+Project-URL: Homepage, https://github.com/eigger/imagespec-designer
+Project-URL: Repository, https://github.com/eigger/imagespec-designer
+Project-URL: Issues, https://github.com/eigger/imagespec-designer/issues
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+License-File: licenses/Apache-2.0.txt
+Requires-Dist: imagespec>=1.0.1
+Requires-Dist: Pillow>=10.4
+Requires-Dist: PyYAML>=6.0.1
+Provides-Extra: ha
+Requires-Dist: homeassistant>=2025.1; extra == "ha"
+Provides-Extra: datamatrix
+Requires-Dist: imagespec[datamatrix]>=1.0.1; extra == "datamatrix"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# imagespec-designer
+
+[![CI](https://github.com/eigger/imagespec-designer/actions/workflows/ci.yml/badge.svg)](https://github.com/eigger/imagespec-designer/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/imagespec-designer)](https://pypi.org/project/imagespec-designer/)
+
+A portable visual editor and Python facade for [`imagespec`](https://github.com/eigger/imagespec). It provides a browser editor, YAML import and export, templates, and rendering helpers. The package requires Python 3.13+ and `imagespec>=1.0.1`; version 0.1.0 was tested with imagespec 1.0.1. Check the installed package version with `imagespec_designer.__version__`.
+
+## Install and run
+
+```sh
+python -m pip install imagespec-designer
+imagespec-designer-demo
+```
+
+Open <http://127.0.0.1:8765>. Install `imagespec-designer[datamatrix]` to render Data Matrix elements.
+
+## Python API
+
+```python
+from imagespec_designer import CanvasProfile, render_image
+
+profile = CanvasProfile(width=296, height=128, palette="bwr")
+payload = [
+    {"type": "rectangle", "x_start": 8, "y_start": 8, "x_end": 287, "y_end": 120, "fill": "black"}
+]
+render_image(payload, profile).save("preview.png")
+```
+
+`CanvasProfile` describes dimensions, rotation, and palette. `RenderContext` accepts host callbacks for fonts, images, and history. The public API also provides document validation, frame compilation, YAML conversion, and pixel-difference helpers.
+
+## Embed the editor
+
+Serve the package's `web` assets and mount an editor instance:
+
+```js
+import { mount } from "/assets/embed.js";
+
+await mount(document.querySelector("#designer"), {
+  title: "Shelf label",
+  apiBase: "/api",
+  profile: { width: 296, height: 128, palette: "bwr" },
+});
+```
+
+The host supplies rendering, profile, transport, and any dynamic values. Unresolved templates can be imported and exported, but the host must evaluate them before rendering. This package covers portable imagespec frame documents; Home Assistant sensor/weather components and integration-specific service workflows remain host responsibilities. See [the embedding API](https://github.com/eigger/imagespec-designer/blob/main/imagespec_designer/web/embed.js) and [development guide](https://github.com/eigger/imagespec-designer/blob/main/docs/development.md).
+
+Code and adapted BLE ESL geometry are MIT licensed. The modified Material Design Icons glyph map is Apache-2.0 licensed. See [NOTICE](NOTICE) and [licenses/Apache-2.0.txt](licenses/Apache-2.0.txt). See [release instructions](https://github.com/eigger/imagespec-designer/blob/main/docs/releasing.md) for PyPI Trusted Publishing setup.

imagespec_designer-0.1.0/README.ko.md

@@ -0,0 +1,30 @@
+# imagespec-designer
+
+[CI](https://github.com/eigger/imagespec-designer/actions/workflows/ci.yml) · [PyPI](https://pypi.org/project/imagespec-designer/)
+
+`imagespec`용 독립 시각 편집기와 Python 렌더링 API입니다. YAML 가져오기/내보내기와 디자인 템플릿을 제공합니다. Python 3.13 이상과 `imagespec>=1.0.1`이 필요하며, 0.1.0은 imagespec 1.0.1에서 테스트했습니다. 설치된 패키지 버전은 `imagespec_designer.__version__`으로 확인할 수 있습니다.
+
+## 설치 및 실행
+
+```sh
+python -m pip install imagespec-designer
+imagespec-designer-demo
+```
+
+`http://127.0.0.1:8765`에서 편집기를 엽니다. Data Matrix 렌더링에는 `imagespec-designer[datamatrix]`를 설치하세요.
+
+## Python API
+
+```python
+from imagespec_designer import CanvasProfile, render_image
+
+profile = CanvasProfile(width=296, height=128, palette="bwr")
+payload = [
+    {"type": "rectangle", "x_start": 8, "y_start": 8, "x_end": 287, "y_end": 120, "fill": "black"}
+]
+render_image(payload, profile).save("preview.png")
+```
+
+삽입 방법과 개발 명령은 [영문 README](https://github.com/eigger/imagespec-designer/blob/main/README.md), [개발 안내](https://github.com/eigger/imagespec-designer/blob/main/docs/development.md)를 참고하세요. 템플릿 값은 호스트가 평가한 뒤 렌더링해야 합니다. Home Assistant 센서/날씨와 통합별 서비스 워크플로는 이 패키지의 범위에 포함되지 않습니다.
+
+코드와 BLE ESL에서 가져온 geometry는 MIT, 수정된 Material Design Icons glyph map은 Apache-2.0 라이선스입니다. 자세한 내용은 [NOTICE](https://github.com/eigger/imagespec-designer/blob/main/NOTICE)와 [Apache-2.0 라이선스](https://github.com/eigger/imagespec-designer/blob/main/licenses/Apache-2.0.txt)를 확인하세요. [릴리스 안내](https://github.com/eigger/imagespec-designer/blob/main/docs/releasing.md)에는 첫 PyPI 게시 설정이 있습니다.

imagespec_designer-0.1.0/README.md

@@ -0,0 +1,47 @@
+# imagespec-designer
+
+[![CI](https://github.com/eigger/imagespec-designer/actions/workflows/ci.yml/badge.svg)](https://github.com/eigger/imagespec-designer/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/imagespec-designer)](https://pypi.org/project/imagespec-designer/)
+
+A portable visual editor and Python facade for [`imagespec`](https://github.com/eigger/imagespec). It provides a browser editor, YAML import and export, templates, and rendering helpers. The package requires Python 3.13+ and `imagespec>=1.0.1`; version 0.1.0 was tested with imagespec 1.0.1. Check the installed package version with `imagespec_designer.__version__`.
+
+## Install and run
+
+```sh
+python -m pip install imagespec-designer
+imagespec-designer-demo
+```
+
+Open <http://127.0.0.1:8765>. Install `imagespec-designer[datamatrix]` to render Data Matrix elements.
+
+## Python API
+
+```python
+from imagespec_designer import CanvasProfile, render_image
+
+profile = CanvasProfile(width=296, height=128, palette="bwr")
+payload = [
+    {"type": "rectangle", "x_start": 8, "y_start": 8, "x_end": 287, "y_end": 120, "fill": "black"}
+]
+render_image(payload, profile).save("preview.png")
+```
+
+`CanvasProfile` describes dimensions, rotation, and palette. `RenderContext` accepts host callbacks for fonts, images, and history. The public API also provides document validation, frame compilation, YAML conversion, and pixel-difference helpers.
+
+## Embed the editor
+
+Serve the package's `web` assets and mount an editor instance:
+
+```js
+import { mount } from "/assets/embed.js";
+
+await mount(document.querySelector("#designer"), {
+  title: "Shelf label",
+  apiBase: "/api",
+  profile: { width: 296, height: 128, palette: "bwr" },
+});
+```
+
+The host supplies rendering, profile, transport, and any dynamic values. Unresolved templates can be imported and exported, but the host must evaluate them before rendering. This package covers portable imagespec frame documents; Home Assistant sensor/weather components and integration-specific service workflows remain host responsibilities. See [the embedding API](https://github.com/eigger/imagespec-designer/blob/main/imagespec_designer/web/embed.js) and [development guide](https://github.com/eigger/imagespec-designer/blob/main/docs/development.md).
+
+Code and adapted BLE ESL geometry are MIT licensed. The modified Material Design Icons glyph map is Apache-2.0 licensed. See [NOTICE](NOTICE) and [licenses/Apache-2.0.txt](licenses/Apache-2.0.txt). See [release instructions](https://github.com/eigger/imagespec-designer/blob/main/docs/releasing.md) for PyPI Trusted Publishing setup.

imagespec_designer-0.1.0/docs/development.md

@@ -0,0 +1,43 @@
+# Development
+
+Create an environment and install the package with its development tools:
+
+```sh
+python3.13 -m venv .venv
+.venv/bin/python -m pip install -e '.[dev,datamatrix]'
+.venv/bin/ruff check .
+.venv/bin/ruff format --check .
+.venv/bin/pytest -q
+```
+
+On Windows, use `.venv\Scripts\python.exe` and `.venv\Scripts\ruff.exe`.
+
+For browser tests, install the locked Node dependencies and Playwright Chromium:
+
+```sh
+npm ci
+npx playwright install chromium
+```
+
+Set `PYTHON` to the environment interpreter before running Playwright so its demo server uses the same installation. On macOS or Linux:
+
+```sh
+PYTHON=.venv/bin/python npm run test:ui
+```
+
+In PowerShell:
+
+```powershell
+$env:PYTHON = ".venv/Scripts/python.exe"
+npm run test:ui
+```
+
+To build and inspect distributions:
+
+```sh
+.venv/bin/python -m build
+.venv/bin/python -m twine check dist/*
+.venv/bin/python scripts/check_dist.py
+```
+
+GitHub Actions runs these checks, tests the lowest allowed direct dependency versions, and smoke-tests an isolated wheel install.

imagespec_designer-0.1.0/docs/releasing.md

@@ -0,0 +1,13 @@
+# Release
+
+Update `project.version` in `pyproject.toml`, merge the change, and create a GitHub Release from the matching `v<version>` tag, such as `v0.1.0`. The release workflow verifies the tag, runs the full CI workflow, then publishes its wheel and source archive to PyPI through OpenID Connect. The GitHub `pypi` environment permits `v*` tags.
+
+Before the first release, register a pending GitHub Trusted Publisher on the [PyPI account Publishing page](https://pypi.org/manage/account/publishing/):
+
+- Project name: `imagespec-designer`
+- Owner: `eigger`
+- Repository: `imagespec-designer`
+- Workflow: `release.yml`
+- Environment: `pypi`
+
+PyPI creates the project after the first successful upload. A pending publisher does not reserve the project name before then. No PyPI API token is needed. Follow [PyPI's guide to creating a project through OIDC](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/) for the account settings steps.

imagespec_designer-0.1.0/imagespec_designer/__init__.py

@@ -0,0 +1,70 @@
+"""Framework-neutral visual design tools for imagespec."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("imagespec-designer")
+except PackageNotFoundError:  # source checkout before installation
+    __version__ = "0+unknown"
+
+from .document import (
+    compile_document,
+    count_pixel_differences,
+    dump_yaml,
+    empty_document,
+    geometry_metadata,
+    import_payload,
+    load_yaml,
+    new_element,
+    validate_document,
+)
+from .facade import (
+    ENGINE_VERSION,
+    MIN_IMAGESPEC_VERSION,
+    TESTED_IMAGESPEC,
+    CanvasProfile,
+    DesignerError,
+    RenderContext,
+    RenderFailure,
+    ValidationError,
+    dither_methods,
+    element_specs,
+    known_types,
+    palette_names,
+    render_image,
+    resolve_templates,
+    starter_types,
+    validate_payload,
+)
+from .templates import apply_template, design_templates
+
+__all__ = [
+    "ENGINE_VERSION",
+    "MIN_IMAGESPEC_VERSION",
+    "TESTED_IMAGESPEC",
+    "CanvasProfile",
+    "DesignerError",
+    "RenderContext",
+    "RenderFailure",
+    "ValidationError",
+    "__version__",
+    "apply_template",
+    "compile_document",
+    "count_pixel_differences",
+    "design_templates",
+    "dither_methods",
+    "dump_yaml",
+    "element_specs",
+    "empty_document",
+    "geometry_metadata",
+    "import_payload",
+    "known_types",
+    "load_yaml",
+    "new_element",
+    "palette_names",
+    "render_image",
+    "resolve_templates",
+    "starter_types",
+    "validate_document",
+    "validate_payload",
+]

imagespec_designer-0.1.0/imagespec_designer/demo.py

@@ -0,0 +1,162 @@
+"""A tiny HTTP host used to try the designer without an application framework."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from io import BytesIO
+from pathlib import Path
+from urllib.parse import urlparse
+
+from . import (
+    ENGINE_VERSION,
+    MIN_IMAGESPEC_VERSION,
+    TESTED_IMAGESPEC,
+    CanvasProfile,
+    ValidationError,
+    __version__,
+    compile_document,
+    element_specs,
+    geometry_metadata,
+    new_element,
+    render_image,
+    starter_types,
+    validate_document,
+)
+from .document import dump_yaml, import_payload, load_yaml
+from .templates import apply_template, design_templates
+
+WEB = Path(__file__).parent / "web"
+
+
+class Handler(SimpleHTTPRequestHandler):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, directory=str(WEB), **kwargs)
+
+    def log_message(self, format, *args):
+        print("[designer] " + format % args)
+
+    def send_json(self, value, status=200):
+        data = json.dumps(value, ensure_ascii=False, default=str).encode()
+        self.send_response(status)
+        self.send_header("content-type", "application/json; charset=utf-8")
+        self.send_header("content-length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def do_GET(self):
+        if self.path.startswith("/api/"):
+            self.send_json({"error": "POST JSON to this endpoint"}, 405)
+            return
+        if self.path.startswith("/assets/"):
+            self.path = self.path.removeprefix("/assets")
+        if self.path in ("/", "/index.html"):
+            self.path = "/index.html"
+        return super().do_GET()
+
+    def do_POST(self):
+        try:
+            length = int(self.headers.get("content-length", "0"))
+            if length > 2 * 1024 * 1024:
+                raise ValidationError("Request is too large")
+            data = json.loads(self.rfile.read(length) or b"{}")
+            profile = make_profile(data.get("profile"))
+            route = urlparse(self.path).path
+            if route == "/api/metadata":
+                result = {
+                    "elements": element_specs(),
+                    "starters": starter_types(),
+                    "geometry": geometry_metadata(),
+                    "designer_version": __version__,
+                    "imagespec_version": ENGINE_VERSION,
+                    "imagespec_minimum_version": MIN_IMAGESPEC_VERSION,
+                    "imagespec_tested_version": TESTED_IMAGESPEC,
+                }
+            elif route == "/api/new-element":
+                result = {"element": new_element(data.get("type", "text"))}
+            elif route == "/api/templates":
+                result = design_templates()
+            elif route == "/api/render":
+                doc = validate_document(data.get("document"), profile)
+                payload = compile_document(doc)
+                image = render_image(payload, profile, background=doc.get("background"))
+                buffer = BytesIO()
+                image.save(buffer, "PNG")
+                result = {
+                    "data_url": "data:image/png;base64,"
+                    + base64.b64encode(buffer.getvalue()).decode()
+                }
+            elif route == "/api/validate":
+                result = {"valid": bool(validate_document(data.get("document"), profile))}
+            elif route == "/api/dump-yaml":
+                result = {"yaml": dump_yaml(data.get("document"))}
+            elif route == "/api/dump-payload":
+                doc = validate_document(data.get("document"), profile)
+                result = {"yaml": dump_yaml(compile_document(doc))}
+            elif route == "/api/parse-yaml":
+                value = load_yaml(data.get("text", ""))
+                if isinstance(value, dict) and value.get("version") == 1:
+                    doc = validate_document(value, profile)
+                    issues = []
+                else:
+                    if (
+                        isinstance(value, dict)
+                        and "data" in value
+                        and isinstance(value["data"], dict)
+                    ):
+                        value = value["data"]
+                    if isinstance(value, dict):
+                        bg = value.get("background")
+                        value = value.get("payload", value.get("elements"))
+                    else:
+                        bg = None
+                    doc, issues = import_payload(value, profile, background=bg)
+                result = {"document": doc, "issues": issues}
+            elif route == "/api/apply-template":
+                result = {
+                    "document": apply_template(data.get("id", ""), profile, data.get("values"))
+                }
+            else:
+                self.send_json({"error": "Unknown endpoint"}, 404)
+                return
+            self.send_json(result)
+        except Exception as exc:  # noqa: BLE001 - HTTP boundary returns errors to the UI.
+            self.send_json({"error": str(exc)}, 400)
+
+
+def make_profile(value):
+    if not isinstance(value, dict):
+        value = {}
+    allowed = {
+        k: value[k]
+        for k in (
+            "width",
+            "height",
+            "rotate",
+            "rotate_mode",
+            "palette",
+            "background",
+            "name",
+        )
+        if k in value
+    }
+    return (
+        CanvasProfile(**allowed)
+        if "width" in allowed and "height" in allowed
+        else CanvasProfile(200, 120, name="Demo display")
+    )
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8765)
+    args = parser.parse_args()
+    print(f"imagespec designer demo: http://{args.host}:{args.port}")
+    ThreadingHTTPServer((args.host, args.port), Handler).serve_forever()
+
+
+if __name__ == "__main__":
+    main()